Searching Text (contains, startswith, match)

"Show me every match played at a stadium with Stadium in its name", "all players whose name starts with R", "every team name containing Super". These are text searches, and they are how you filter rows by text in pandas. The searching methods return a True/False Series, which you drop straight into df[...] — exactly like a numeric condition df[df["runs"] > 50].

Definition

String-search methods test or locate a pattern inside each string. Test methods (contains, startswith, endswith, match, fullmatch) return a boolean Series — True where the string has the pattern — that can be used as a row filter. Locate methods (find, count) return numbers: the position of the first match, or how many times it occurs.

• Pattern — a plain substring ("Super") or a regular expression ("^R", "Kings|Royals").
• Row filter — df[df["team"].str.contains("Kings")] keeps matching rows.
• Position — counted from 0; -1 means "not found".

Syntax

s.str.contains(pat, case=True, flags=0, na=<default>, regex=True)
s.str.startswith(pat, na=<default>)      # pat can be a tuple of strings
s.str.endswith(pat, na=<default>)
s.str.match(pat, case=True, na=<default>)      # regex must match at the START
s.str.fullmatch(pat, case=True, na=<default>)  # regex must match the WHOLE string
s.str.find(sub, start=0, end=None)       # position of first occurrence, -1 if none
s.str.count(pat)                         # number of (regex) occurrences

Example — contains as a filter

teams = pd.DataFrame({
    "team":   ["Chennai Super Kings", "Mumbai Indians", "Kings XI Punjab",
               "Rajasthan Royals", "Royal Challengers Bangalore", None],
    "titles": [5, 5, 0, 1, 0, 0],
})
print(teams["team"].str.contains("Kings"))
print(teams[teams["team"].str.contains("Kings")])

0     True
1    False
2     True
3    False
4    False
5    False
Name: team, dtype: bool
                  team  titles
0  Chennai Super Kings       5
2      Kings XI Punjab       0

How it works: contains("Kings") returns True for rows where the substring appears anywhere. The missing name gives False, so the mask is a clean boolean filter.

Example — case=False and na=

print(teams[teams["team"].str.contains("royal", case=False)])
print(teams["team"].str.contains("Kings", na=True).tolist())

                          team  titles
3             Rajasthan Royals       1
4  Royal Challengers Bangalore       0
[True, False, True, False, False, True]

How it works: case=False matches Royals and Royal regardless of capital letters. na=True decides what missing values become in the mask — here they would be kept by a filter.

Note (pandas 3): for the new str dtype, missing values give False by default. In pandas 2 (object dtype) they gave NaN, and df[mask] failed with "Cannot mask with non-boolean array containing NA / NaN values" — which is why old code often writes na=False. Writing na=False explicitly is still a good habit.

Example — regex power: OR, start, end

contains treats the pattern as a regular expression by default:

t = teams["team"]
print(t[t.str.contains("Kings|Royals", na=False)].tolist())   # | means OR
print(t[t.str.contains("^R", na=False)].tolist())             # ^ = starts with
print(t[t.str.contains("s$", na=False)].tolist())             # $ = ends with

['Chennai Super Kings', 'Kings XI Punjab', 'Rajasthan Royals']
['Rajasthan Royals', 'Royal Challengers Bangalore']
['Chennai Super Kings', 'Mumbai Indians', 'Rajasthan Royals']

Example — special characters: regex=False

venues = pd.Series(["Eden Gardens", "Feroz Shah Kotla (Arun Jaitley)", "Wankhede Stadium"])
print(venues.str.contains("(", regex=False).tolist())
print(venues.str.contains(".", regex=False).tolist())
print(venues.str.contains(".").tolist())

[False, True, False]
[False, False, False]
[True, True, True]

How it works: in regex, ( starts a group and . means "any character". With regex=False they are matched literally. Without it, "." matches every non-empty string — a classic bug.

Example — startswith / endswith / match

players = pd.Series(["Rohit Sharma", "Rishabh Pant", "Virat Kohli", "Ravindra Jadeja", "KL Rahul"])
print(players[players.str.startswith("R")].tolist())
print(players[players.str.startswith(("V", "K"))].tolist())   # tuple = any of these
print(players[players.str.endswith("a")].tolist())
print(players.str.match(r"R\w+ [A-Z]").tolist())

['Rohit Sharma', 'Rishabh Pant', 'Ravindra Jadeja']
['Virat Kohli', 'KL Rahul']
['Rohit Sharma', 'Ravindra Jadeja']
[True, True, False, True, False]

startswith / endswith take plain text (no regex), and accept a tuple for several options. match is regex-based but anchored at the start; fullmatch requires the whole string to match.

Example — find and count

print(pd.DataFrame({
    "player": players,
    "find_a": players.str.find("a"),
    "count_a": players.str.count("a"),
    "words": players.str.count(" ") + 1,
}))

            player  find_a  count_a  words
0     Rohit Sharma       8        2      2
1     Rishabh Pant       4        2      2
2      Virat Kohli       3        1      2
3  Ravindra Jadeja       1        4      2
4         KL Rahul       4        1      2

How it works: find("a") gives the index of the first lowercase a (-1 if none — Virat has a lowercase a at position 3). count("a") counts every occurrence (it is regex-based, so escape special characters).

Comparison — which search method?

Common mistakes

• ❌ df[df["team"] == "Kings"] expecting partial matches. ✅ == compares whole values; use str.contains("Kings").
• ❌ contains("(") → regex error; contains(".") → matches everything. ✅ regex=False for literal text.
• ❌ Forgetting case=False and missing "royal challengers". ✅ contains("royal", case=False).
• ❌ startswith("R|V") — startswith is not regex. ✅ startswith(("R", "V")).
• ❌ Using ~ (NOT) on a mask with NaN from old object columns. ✅ Pass na=False first.

Interview tip

Q: Difference between str.contains, str.match and str.fullmatch? A: contains finds the pattern anywhere, match requires it at the start of the string, fullmatch requires the entire string to match.