Matcher · spaCy API Documentation

Matcher.init method

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.

Name	Type	Description
`vocab`	`Vocab`	The vocabulary object, which must be shared with the documents the matcher will operate on.
`validate` v2.1	bool	Validate all patterns added to this matcher.
RETURNS	`Matcher`	The newly constructed object.

Matcher.call method

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

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
`doc`	`Doc`	The document 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 method

Match a stream of documents, yielding them in turn.

Name	Type	Description
`docs`	iterable	A stream of documents.
`batch_size`	int	The number of documents to accumulate into a working set.
`return_matches` v2.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 methodv2.0

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.

Name	Type	Description
RETURNS	int	The number of rules.

Matcher.contains methodv2.0

Check whether the matcher contains rules for a match ID.

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

Matcher.add methodv2.0

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`	unicode	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.

Changed in v2.2.2

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 methodv2.0

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

Name	Type	Description
`key`	unicode	The ID of the match rule.

Matcher.get methodv2.0

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

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

Dec	JAN	Feb
	06
2019	2020	2021

Pipeline

Matcher.__init__ method

Matcher.__call__ method