Working with spaCy Matcher

Pattern Limit in Matcher

There isn't a hard limit on the number of patterns you can add to spaCy's Matcher class, but it's constrained by system memory and pattern complexity. You can typically add thousands of patterns, but keep an eye on performance.


Saving and Loading Matcher Objects

You can save a Matcher object with its patterns to disk and load it back into your program using spaCy's to_disk and from_disk methods.

Saving the Matcher Object

  1. Use the to_disk method to save the Matcher object after adding your patterns.
  2. Specify the directory path for saving the object.

Loading the Matcher Object

  1. Create a new Matcher object with the same or a similar nlp object.
  2. Use the from_disk method to load the saved patterns.

Example Code:

import spacy from spacy.matcher import Matcher # Assuming you have an NLP object and a Matcher nlp = spacy.load("en_core_web_sm") matcher = Matcher(nlp.vocab) # Add your patterns pattern = [{"LOWER": "hello"}, {"LOWER": "world"}] matcher.add("HelloWorld", [pattern]) # Save the Matcher matcher.to_disk("./matcher") # Load the Matcher new_matcher = Matcher(nlp.vocab) new_matcher.from_disk("./matcher")

Ensure the nlp object is compatible when loading the Matcher to preserve vocabulary consistency.


Matchers are utilized for identifying phrases, tags, and entity matches. Unlike the application of regular expressions to plain text, spaCy's rule-based matching engine and its components not only enable the identification of desired words and phrases but also facilitate access to tags and their interrelations within a document. This capability allows for straightforward manipulation and analysis of adjacent tags, consolidation of scopes into a single tag, or the augmentation of named entities within doc.ents. For intricate tasks, training statistical models for entity recognition is often more advantageous. Nevertheless, these models necessitate training data and the loading of such data, making rule-based methods more feasible in numerous instances. This is particularly pertinent at the inception of a project, where rule-based techniques can assist in steering the statistical model throughout the data gathering phase. If specific examples are provided with the intention for the system to extrapolate from them, model training can be beneficial, especially when local contextual information is available. For instance, in endeavors to identify individual or company names, a statistical model for named entity recognition might prove advantageous. Conversely, a rule-based system is advisable for identifying a relatively finite set of examples within your data or when patterns can be explicitly defined through tagging rules or regular expressions. For instance, employing a purely rule-based strategy might suffice for recognizing country names, professions, competitions, skills, IP addresses, or URLs. Integrating both approaches, where rules enhance statistical models for handling particular scenarios with improved precision, is also viable. Refer to the Rules-Based Entity Detection section for additional details. The EntityRuler component enables the incorporation of named entities based on a schema dictionary, facilitating the amalgamation of rule-based and statistical named entity recognition for the development of more robust pipelines. 

You can use the Matcher Explorer pattern generation tool.