spaCy/website/docs/api/matcher.md

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

As of spaCy 2.0, Matcher.add_pattern and Matcher.add_entity are deprecated and have been replaced with a simpler Matcher.add that lets you add a list of patterns and a callback for a given match ID. Matcher.get_entity is now called matcher.get. Matcher.load (not useful, as it didn't allow specifying callbacks), and Matcher.has_entity (now redundant) have been removed. The concept of "acceptor functions" has also been retired – this logic can now be handled in the callback functions.

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.
RETURNS	Matcher	The newly constructed object.

Matcher.__call__

Find all token sequences matching the supplied patterns on the Doc. As of spaCy v2.3, the Matcher can also be called on Span objects.

Example

from spacy.matcher import Matcher

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

Name	Type	Description
doclike	Doc/Span	The document to match over or a Span (as of v2.3).
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.

By default, the matcher does not perform any action on matches, like tagging matched phrases with entity types. Instead, actions need to be specified when adding patterns or entities, by passing in a callback function as the on_match argument on add. This allows you to define custom actions per pattern within the same matcher. For example, you might only want to merge some entity types, and set custom flags for other matched patterns. For more details and examples, see the usage guide on rule-based matching.

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", None, [{"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', None, [{'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)
  matcher.add("HelloWorld", on_match, [{"LOWER": "hello"}, {"LOWER": "world"}])
  matcher.add("GoogleMaps", on_match, [{"ORTH": "Google"}, {"ORTH": "Maps"}])
  doc = nlp("HELLO WORLD on Google Maps.")
  matches = matcher(doc)

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

As of spaCy 2.2.2, Matcher.add also supports the new API, which will become the default in the future. The patterns are now the second argument and a list (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", None, *patterns)
+ matcher.add("GoogleNow", patterns)
- matcher.add("GoogleNow", on_match, *patterns)
+ matcher.add("GoogleNow", patterns, on_match=on_match)

Matcher.remove

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

Example

matcher.add("Rule", None, [{"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", None, [{"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.