spaCy/website/docs/api/matcher.md

title	teaser	tag	source
Matcher	Match sequences of tokens, based on pattern rules	class	spacy/matcher/matcher.pyx

Matcher.__init__

Create the rule-based Matcher. If validate=True is set, all patterns added to the matcher will be validated against a JSON schema and a MatchPatternError is raised if problems are found. Those can include incorrect types (e.g. a string where an integer is expected) or unexpected property names.

Example

from spacy.matcher import Matcher
matcher = Matcher(nlp.vocab)

Name	Type	Description
vocab	Vocab	The vocabulary object, which must be shared with the documents the matcher will operate on.
validate 2.1	bool	Validate all patterns added to this matcher.

Matcher.__call__

Find all token sequences matching the supplied patterns on the Doc or Span.

Example

from spacy.matcher import Matcher

matcher = Matcher(nlp.vocab)
pattern = [{"LOWER": "hello"}, {"LOWER": "world"}]
matcher.add("HelloWorld", [pattern])
doc = nlp("hello world!")
matches = matcher(doc)

Name	Type	Description
doclike	Doc/Span	The Doc or Span to match over.
RETURNS	list	A list of (match_id, start, end) tuples, describing the matches. A match tuple describes a span doc[start:end]. The match_id is the ID of the added match pattern.

Matcher.pipe

Match a stream of documents, yielding them in turn.

Example

from spacy.matcher import Matcher
matcher = Matcher(nlp.vocab)
for doc in matcher.pipe(docs, batch_size=50):
    pass

Name	Type	Description
docs	iterable	A stream of documents.
batch_size	int	The number of documents to accumulate into a working set.
return_matches 2.1	bool	Yield the match lists along with the docs, making results (doc, matches) tuples.
as_tuples	bool	Interpret the input stream as (doc, context) tuples, and yield (result, context) tuples out. If both return_matches and as_tuples are True, the output will be a sequence of ((doc, matches), context) tuples.
YIELDS	Doc	Documents, in order.

Matcher.__len__

Get the number of rules added to the matcher. Note that this only returns the number of rules (identical with the number of IDs), not the number of individual patterns.

Example

matcher = Matcher(nlp.vocab)
assert len(matcher) == 0
matcher.add("Rule", [[{"ORTH": "test"}]])
assert len(matcher) == 1

Name	Type	Description
RETURNS	int	The number of rules.

Matcher.__contains__

Check whether the matcher contains rules for a match ID.

Example

matcher = Matcher(nlp.vocab)
assert "Rule" not in matcher
matcher.add("Rule", [[{'ORTH': 'test'}]])
assert "Rule" in matcher

Name	Type	Description
key	str	The match ID.
RETURNS	bool	Whether the matcher contains rules for this match ID.

Matcher.add

Add a rule to the matcher, consisting of an ID key, one or more patterns, and a callback function to act on the matches. The callback function will receive the arguments matcher, doc, i and matches. If a pattern already exists for the given ID, the patterns will be extended. An on_match callback will be overwritten.

Example

def on_match(matcher, doc, id, matches):
    print('Matched!', matches)

matcher = Matcher(nlp.vocab)
patterns = [
   [{"LOWER": "hello"}, {"LOWER": "world"}],
   [{"ORTH": "Google"}, {"ORTH": "Maps"}]
]
matcher.add("TEST_PATTERNS", patterns)
doc = nlp("HELLO WORLD on Google Maps.")
matches = matcher(doc)

As of spaCy v3.0, Matcher.add takes a list of patterns as the second argument (instead of a variable number of arguments). The on_match callback becomes an optional keyword argument.

patterns = [[{"TEXT": "Google"}, {"TEXT": "Now"}], [{"TEXT": "GoogleNow"}]]
- matcher.add("GoogleNow", on_match, *patterns)
+ matcher.add("GoogleNow", patterns, on_match=on_match)

Name	Type	Description
match_id	str	An ID for the thing you're matching.
patterns	list	Match pattern. A pattern consists of a list of dicts, where each dict describes a token.
keyword-only
on_match	callable or None	Callback function to act on matches. Takes the arguments matcher, doc, i and matches.

Matcher.remove

Remove a rule from the matcher. A KeyError is raised if the match ID does not exist.

Example

matcher.add("Rule", [[{"ORTH": "test"}]])
assert "Rule" in matcher
matcher.remove("Rule")
assert "Rule" not in matcher

Name	Type	Description
key	str	The ID of the match rule.

Matcher.get

Retrieve the pattern stored for a key. Returns the rule as an (on_match, patterns) tuple containing the callback and available patterns.

Example

matcher.add("Rule", [[{"ORTH": "test"}]])
on_match, patterns = matcher.get("Rule")

Name	Type	Description
key	str	The ID of the match rule.
RETURNS	tuple	The rule, as an (on_match, patterns) tuple.