A spaCy Matcher finds token sequences that satisfy rules about words and their attributes. It is useful when a relationship can appear in several forms: “Desoto met the Pascagoula” and “Lewis and Clark met their first Mandan Chief” both contain a meeting, but the words between the participants differ. Matcher rules can use part-of-speech tags, lemmas, and optional or repeated tokens instead of requiring one exact phrase. section 11.7.1
Find a meeting phrase
```python import spacy from spacy.matcher import Matcher nlp = spacy.load('en_core_web_md') pattern = [ {'POS': {'IN': ['NOUN', 'PROPN']}, 'OP': '+'}, {'IS_ALPHA': True, 'OP': '*'}, {'LEMMA': 'meet'}, {'IS_ALPHA': True, 'OP': '*'}, {'POS': {'IN': ['NOUN', 'PROPN']}, 'OP': '+'} ] matcher = Matcher(nlp.vocab) matcher.add('met', [pattern]) doc = nlp('In 1541 Desoto met the Pascagoula.') for match_id, start, stop in matcher(doc): print(doc[start:stop]) # Desoto met the Pascagoula ``` Each result contains a match ID and start and stop token positions. Slice the processed document with those positions to inspect the matched words. section 11.7.1 section 10.1.3
Inspect the tagged tokens before writing a rule: a meeting sentence can contain proper nouns, a verb whose lemma is “meet,” and intervening words such as “the.” The `OP` entries above permit runs of noun or proper-noun tokens and zero or more alphabetic tokens. This flexibility does not cover every sentence. The initial pattern, for example, returns no match for “Gorbachev and Reagan met at Höfði house”; a coordinated-subject pattern is another variation to add. Treat a matched span as a candidate for relation extraction, not as a guarantee that every meeting has been found. section 11.7.1
Other practical uses and boundaries:
- For a known word list, a rule using `LOWER`, `IN`, and `FUZZY1` can flag a spelling variation such as “Tilenol.” The returned span can be highlighted or used in a replacement workflow. section 10.1.3
- Rule-based filters can support LLM guardrails, but trying to enumerate every malicious prompt becomes a whack-a-mole task. More complex detection may call for a different approach. section 10.1.3
- To test a rule beyond meeting phrases, try finding additional named entities for Timnit Gebru’s places of work in Wikipedia articles. section 11.10
