Lucene-querysyntaxis in Azure Cognitive Search

Wanneer u query's maakt in Azure Cognitive Search, kunt u kiezen voor de volledige Lucene Query Parser-syntaxis voor gespecialiseerde queryformulieren: jokertekens, fuzzy zoekopdrachten, nabijheid zoeken, reguliere expressies. Een groot deel van de Lucene Query Parser-syntaxis wordt intact geïmplementeerd in Azure Cognitive Search, met uitzondering van *bereikzoekopdrachten, die worden opgebouwd via $filter expressies.

Als u de volledige Lucene-syntaxis wilt gebruiken, stelt u queryType in op 'full' en geeft u een query-expressie door die is gebaseerd op jokertekens, fuzzy zoekopdrachten of een van de andere queryformulieren die door de volledige syntaxis worden ondersteund. In REST worden queryexpressies opgegeven in de search parameter van een REST API-aanvraag (Search Documents).

Voorbeeld (volledige syntaxis)

Het volgende voorbeeld is een zoekaanvraag die is samengesteld met behulp van de volledige syntaxis. In dit specifieke voorbeeld ziet u zoeken in het veld en het stimuleren van termen. Er wordt gezocht naar hotels waar het categorieveld de term 'budget' bevat. Documenten met de zin 'onlangs gerenoveerd' worden hoger gerangschikt als gevolg van de term boostwaarde (3).

POST /indexes/hotels-sample-index/docs/search?api-version=2020-06-30
{
  "queryType": "full",
  "search": "category:budget AND \"recently renovated\"^3",
  "searchMode": "all"
}

Hoewel de parameter niet specifiek is voor een querytype, is deze searchMode wel relevant in dit voorbeeld. Wanneer operators zich in de query bevinden, moet u over het algemeen instellen searchMode=all om ervoor te zorgen dat aan alle criteria wordt voldaan.

Zie Voorbeelden van Lucene-querysyntaxis voor meer voorbeelden. Zie Search Documents (REST API) voor meer informatie over de queryaanvraag en parameters, waaronder searchMode.

Basisprincipes van syntaxis

De volgende syntaxisfundamenten zijn van toepassing op alle query's die gebruikmaken van de Lucene-syntaxis.

Operatorevaluatie in context

Plaatsing bepaalt of een symbool wordt geïnterpreteerd als een operator of gewoon een ander teken in een tekenreeks.

In de volledige syntaxis van Lucene wordt bijvoorbeeld de tilde (~) gebruikt voor zowel fuzzy zoeken als zoeken in nabijheid. Wanneer ~ wordt geplaatst na een woordgroep met aanhalingstekens, roept de nabijheidszoekopdracht aan. Wanneer ~ aan het einde van een term wordt geplaatst, roept fuzzy zoekopdracht aan.

Binnen een term, zoals 'business~analyst', wordt het teken niet geëvalueerd als een operator. In dit geval, ervan uitgaande dat de query een term of woordgroepsquery is, wordt zoeken in volledige tekst met lexicale analyse de ~ uitgesplitsd en wordt de term 'business~analyst' in tweeën gesplitst: bedrijfs- OF analist.

Het bovenstaande voorbeeld is de tilde (~), maar hetzelfde principe is van toepassing op elke operator.

Escape-speciale tekens

Als u een van de zoekoperators als onderdeel van de zoektekst wilt gebruiken, moet u het teken laten ontsnappen door er één backslash (\) voor te plaatsen. Voor een zoekopdracht met jokertekens op https://, waarbij :// deel uitmaakt van de queryreeks, geeft search=https\:\/\/*u op. Op dezelfde manier kan een patroon voor een telefoonnummer met escape-tekens er als volgt \+1 \(800\) 642\-7676uitzien.

Speciale tekens waarvoor escape vereist is, zijn onder andere:
+ - & | ! ( ) { } [ ] ^ " ~ * ? : \ /

Notitie

Hoewel escape-tokens bijeenhoudt, kan lexicale analyse tijdens het indexeren ze verwijderen. De standaard Lucene-analyse breekt bijvoorbeeld woorden over afbreekstreepjes, witruimte en andere tekens. Als u speciale tekens in de querytekenreeks nodig hebt, hebt u mogelijk een analysefunctie nodig waarmee ze in de index worden bewaard. Sommige opties zijn Microsoft natuurlijke taalanalyses, waarmee woorden met afbreekstreepjes behouden blijven, of een aangepaste analyse voor complexere patronen. Zie Gedeeltelijke termen, patronen en speciale tekens voor meer informatie.

Onveilige en gereserveerde tekens in URL's coderen

Zorg ervoor dat alle onveilige en gereserveerde tekens zijn gecodeerd in een URL. '#' is bijvoorbeeld een onveilig teken omdat het een fragment-/anker-id in een URL is. Het teken moet worden gecodeerd als %23 het wordt gebruikt in een URL. '&' en '=' zijn voorbeelden van gereserveerde tekens die parameters scheiden en waarden opgeven in Azure Cognitive Search. Zie RFC1738: Uniform Resource Locators (URL) voor meer informatie.

Onveilige tekens zijn " ` < > # % { } | \ ^ ~ [ ]. Gereserveerde tekens zijn ; / ? : @ = + &.

Booleaanse operatoren

U kunt Booleaanse operators insluiten in een querytekenreeks om de nauwkeurigheid van een overeenkomst te verbeteren. De volledige syntaxis ondersteunt tekstoperatoren naast tekenoperators. Geef altijd booleaanse tekstoperatoren (AND, OR, NOT) op in hoofdletters.

Tekstoperator Teken Voorbeeld Gebruik
EN + wifi AND luxury Hiermee geeft u termen op die een overeenkomst moet bevatten. In het voorbeeld zoekt de query-engine naar documenten die zowel als wifiluxurybevatten. Het plusteken (+) kan ook direct voor een term worden gebruikt om dit verplicht te maken. Bepaalt bijvoorbeeld +wifi +luxury dat beide termen ergens in het veld van één document moeten worden weergegeven.
OF (geen) 1 wifi OR luxury Hiermee wordt een overeenkomst gevonden wanneer een van de termen wordt gevonden. In het voorbeeld retourneert de query-engine overeenkomst voor documenten die of wifi of luxury beide bevatten. Omdat OF de standaardoperator voor combinaties is, kunt u deze ook weglaten, zodat wifi luxury het equivalent van wifi OR luxuryis.
NOT !, - wifi –luxury Retourneert overeenkomsten voor documenten die de term uitsluiten. Zoekt bijvoorbeeld naar documenten die wel de wifi term hebben, wifi –luxury maar niet luxury.

Het is belangrijk te weten dat de not-operator (NOT, !of -) zich in de volledige syntaxis anders gedraagt dan in eenvoudige syntaxis. In de volledige syntaxis worden negaties altijd ANDed op de query, zodanig dat wifi -luxury wordt geïnterpreteerd als 'wifi EN NIET luxe', ongeacht of de searchMode parameter is ingesteld op any of all. Dit geeft u standaard een intuïtiever gedrag voor negaties.

Een enkele ontkenning, zoals de query -luxury , is niet toegestaan in de volledige zoeksyntaxis en retourneert altijd een lege resultatenset.

1 Het | teken wordt niet ondersteund voor OR-bewerkingen.

Veldzoekopdracht

U kunt een veldzoekbewerking definiëren met de fieldName:searchExpression syntaxis, waarbij de zoekexpressie een enkel woord of een woordgroep kan zijn, of een complexere expressie tussen haakjes, optioneel met Booleaanse operatoren. Enkele voorbeelden zijn:

  • genre:jazz NIET geschiedenis

  • artiesten:("Miles Davis" "John Coltrane")

Zorg ervoor dat u meerdere tekenreeksen tussen aanhalingstekens plaatst als u wilt dat beide tekenreeksen als één entiteit worden geëvalueerd, in dit geval zoeken naar twee afzonderlijke artiesten in het artists veld.

Het opgegeven veld in fieldName:searchExpression moet een searchable veld zijn. Zie Index maken voor meer informatie over hoe indexkenmerken worden gebruikt in velddefinities.

Notitie

Wanneer u veldzoekexpressies gebruikt, hoeft u de searchFields parameter niet te gebruiken, omdat elke veldzoekexpressie expliciet een veldnaam heeft opgegeven. U kunt echter nog steeds de searchFields parameter gebruiken als u een query wilt uitvoeren waarbij sommige onderdelen zijn gericht op een specifiek veld en de rest kan van toepassing zijn op verschillende velden. De query search=genre:jazz NOT history&searchFields=description komt bijvoorbeeld alleen overeen jazz met het genre veld, terwijl deze overeenkomt NOT history met het description veld. De veldnaam die is opgegeven in fieldName:searchExpression heeft altijd voorrang op de searchFields parameter. Daarom hoeven we in dit voorbeeld niet op te nemen genre in de searchFields parameter.

Fuzzy zoekopdracht

Een fuzzy zoekopdracht vindt overeenkomsten in termen die een vergelijkbare constructie hebben, waardoor een term wordt uitgebreid tot het maximum van 50 termen die voldoen aan de afstandscriteria van twee of minder. Zie Fuzzy zoeken voor meer informatie.

Als u een fuzzy zoekopdracht wilt uitvoeren, gebruikt u het tildeteken '~' aan het einde van een enkel woord met een optionele parameter, een getal tussen 0 en 2 (standaard), dat de bewerkingsafstand aangeeft. 'blauw~' of 'blauw~1' retourneert bijvoorbeeld 'blauw', 'blauw' en 'lijm'.

Fuzzy zoekopdrachten kunnen alleen worden toegepast op termen, niet op woordgroepen, maar u kunt de tilde aan elke term afzonderlijk toevoegen in een meerdelige naam of woordgroep. 'Unviersty~ of~ 'Wshington~' komt bijvoorbeeld overeen met 'University of Washington'.

Nabijheid zoeken

Nabijheidszoekopdrachten worden gebruikt om termen te vinden die dicht bij elkaar in een document staan. Voeg een tilde '~'-symbool in aan het einde van een woordgroep, gevolgd door het aantal woorden dat de nabijheidsgrens maakt. Vindt bijvoorbeeld "hotel airport"~5 de termen 'hotel' en 'airport' binnen vijf woorden van elkaar in een document.

Term boost

Termverbetering verwijst naar het hoger rangschikken van een document als het de versterkte term bevat, ten opzichte van documenten die de term niet bevatten. Dit verschilt van scoreprofielen omdat scoreprofielen bepaalde velden verbeteren in plaats van specifieke termen.

In het volgende voorbeeld worden de verschillen geïllustreerd. Stel dat er een scoreprofiel is dat overeenkomsten in een bepaald veld verhoogt, bijvoorbeeld genre in het voorbeeld musicstoreindex. Termverbetering kan worden gebruikt om bepaalde zoektermen verder te verhogen dan andere. Hiermee worden documenten die de zoektermen in het genreveld bevatten bijvoorbeeld rock^2 electronic hoger verhoogd dan andere doorzoekbare velden in de index. Verder worden documenten die de zoekterm rock bevatten, hoger gerangschikt dan de andere elektronische zoekterm als gevolg van de term boost-waarde (2).

Als u een term een boost wilt geven, gebruikt u het caretteken ^, met een boostfactor (een getal) aan het einde van de term die u zoekt. U kunt ook woordgroepen een boost geven. Hoe hoger de boostfactor, hoe relevanter de term is ten opzichte van andere zoektermen. De boostfactor is standaard 1. Hoewel de boostfactor positief moet zijn, kan deze kleiner zijn dan 1 (bijvoorbeeld 0,20).

Zoeken in reguliere expressies

Met een reguliere expressiezoekactie wordt een overeenkomst gevonden op basis van patronen die geldig zijn onder Apache Lucene, zoals beschreven in de klasse RegExp. In Azure Cognitive Search wordt een reguliere expressie tussen slashes /ingesloten.

Als u bijvoorbeeld documenten wilt zoeken die 'motel' of 'hotel' bevatten, geeft u /[mh]otel/op. Zoekopdrachten met reguliere expressies worden vergeleken met enkele woorden.

Sommige hulpprogramma's en talen leggen andere vereisten voor escapetekens op. Voor JSON worden tekenreeksen met een slash met een schuine streep naar achteren geslashd: 'microsoft.com/azure/' wordt search=/.*microsoft.com\/azure\/.*/ de plaats waar search=/.* <string-placeholder>.*/ de reguliere expressie wordt ingesteld en microsoft.com\/azure\/ is de tekenreeks met een slash met escaped.

Twee veelvoorkomende symbolen in regex-query's zijn . en *. Een . komt overeen met een willekeurig teken en een * komt overeen met het vorige teken nul of meer keren. Komt bijvoorbeeld /be./ overeen met de termen 'bee' en 'bet' terwijl /be*/ 'be', 'bee' en 'beee' overeenkomen, maar niet 'bet'. Samen kunt u elke reeks tekens vinden, zodat /be.*/ deze overeenkomt met elke term die begint met 'zijn', .* zoals 'beter'.

Zoeken met jokertekens

U kunt de algemeen herkende syntaxis gebruiken voor zoekopdrachten met jokertekens met meerdere (*) of één (?). Volledige Lucene-syntaxis ondersteunt het overeenkomen van voorvoegsels, invoegsels en achtervoegsels.

Let op: de Lucene-queryparser ondersteunt het gebruik van deze symbolen met één term en niet met een woordgroep.

Type bevestiging Beschrijving en voorbeelden
Voorvoegsel Termfragment komt vóór * of ?. Een query-expressie van search=alpha* retourneert bijvoorbeeld 'alfanumeriek' of 'alfabetisch'. Het vergelijken van voorvoegsels wordt ondersteund in zowel eenvoudige als volledige syntaxis.
achtervoegsel Termfragment komt na * of ?, met een schuine streep om de constructie te scheiden. Retourneert bijvoorbeeld search=/.*numeric/ 'alfanumeriek'.
Infix Termfragmenten omsluiten * of ?. Retourneert bijvoorbeeld search=non*al 'niet-numeriek' en 'onzinnig'.

U kunt operators combineren in één expressie. Komt bijvoorbeeld 980?2* overeen met '98072-1222' en '98052-1234', waarbij ? overeenkomsten op één (vereist) teken en * overeenkomsten op tekens met een willekeurige lengte die volgen.

Voor het overeenkomende achtervoegsel zijn de reguliere expressie slash-scheidingstekens / vereist. Over het algemeen kunt u het * symbool of ? niet gebruiken als het eerste teken van een term, zonder de /. Het is ook belangrijk om te weten dat de * zich anders gedraagt wanneer deze wordt gebruikt buiten regex-query's. Buiten of de regex slash-scheidingstekens / , is de * een jokerteken en komt overeen met elke reeks tekens, vergelijkbaar met .* in regex. Als voorbeeld search=/non.*al/ wordt dezelfde resultatenset geproduceerd als search=non*al.

Notitie

In de regel is het vergelijken van patronen traag, dus misschien wilt u alternatieve methoden verkennen, zoals edge n-gram-tokenisatie waarmee tokens worden gemaakt voor reeksen tekens in een term. Met n-gram-tokenisatie is de index groter, maar query's kunnen sneller worden uitgevoerd, afhankelijk van de patroonconstructie en de lengte van tekenreeksen die u indexeert. Zie Gedeeltelijke zoektermen en patronen met speciale tekens voor meer informatie.

Impact van een analyse op jokertekenquery's

Tijdens het parseren van query's worden query's die zijn geformuleerd als voorvoegsel, achtervoegsel, jokerteken of reguliere expressies ongewijzigd doorgegeven aan de querystructuur, waardoor lexicale analyse wordt overgeslagen. Overeenkomsten worden alleen gevonden als de index de tekenreeksen bevat in de indeling die uw query opgeeft. In de meeste gevallen hebt u tijdens het indexeren een analyse nodig die tekenreeksintegriteit behoudt, zodat gedeeltelijke overeenkomst tussen termen en patronen slaagt. Zie Gedeeltelijke zoektermen zoeken in Azure Cognitive Search query's voor meer informatie.

Overweeg een situatie waarin u mogelijk wilt dat de zoekquery 'terminat*' resultaten retourneert die termen bevatten zoals 'beëindigen', 'beëindiging' en 'beëindigen'.

Als u de analyse en.lucene (Engels Lucene) zou gebruiken, zou deze agressieve stemming van elke term toepassen. Bijvoorbeeld: 'beëindigen', 'beëindiging', 'beëindigen' worden allemaal tokenized tot het token 'termi' in uw index. Aan de andere kant worden termen in query's met jokertekens of fuzzy zoekopdrachten helemaal niet geanalyseerd, zodat er geen resultaten zijn die overeenkomen met de 'terminat*'-query.

Aan de andere kant zijn de Microsoft analyzers (in dit geval de en.microsoft analyzer) iets geavanceerder en gebruiken ze lemmatisatie in plaats van stemming. Dit betekent dat alle gegenereerde tokens geldige Engelse woorden moeten zijn. 'beëindigen', 'beëindigt' en 'beëindiging' blijven bijvoorbeeld meestal heel in de index en is een voorkeurskeuze voor scenario's die veel afhankelijk zijn van jokertekens en fuzzy zoekopdrachten.

Query's met jokertekens en regexs scoren

Azure Cognitive Search maakt gebruik van scoren op basis van frequentie (BM25) voor tekstquery's. Voor jokertekens en regex-query's waarbij het bereik van termen mogelijk breed kan zijn, wordt de frequentiefactor echter genegeerd om te voorkomen dat de classificatie bevooroordeeld wordt naar overeenkomsten van zeldzamer termen. Alle overeenkomsten worden gelijk behandeld voor zoekopdrachten met jokertekens en regex-zoekopdrachten.

Speciale tekens

In sommige gevallen kunt u zoeken naar een speciaal teken, zoals een emoji ❤ of het €-teken. In dergelijke gevallen moet u ervoor zorgen dat de analyse die u gebruikt, deze tekens niet filtert. Met de standaardanalyse worden veel speciale tekens omzeild, waardoor deze uit de index worden uitgesloten.

Analysers die speciale tekens tokeniseren, zijn onder andere de 'witruimte'-analyse, die rekening houdt met tekenreeksen gescheiden door witruimten als tokens (dus de tekenreeks ❤ wordt beschouwd als een token). Een taalanalyse zoals de Microsoft English analyzer ('en.microsoft'), zou ook de tekenreeks '€' als token gebruiken. U kunt een analyse testen om te zien welke tokens er worden gegenereerd voor een bepaalde query.

Wanneer u Unicode-tekens gebruikt, moet u ervoor zorgen dat symbolen correct zijn ge escaped in de query-URL (bijvoorbeeld voor '❤' gebruikt u de escape-reeks %E2%9D%A4+). Postman voert deze vertaling automatisch uit.

Prioriteit (groeperen)

U kunt haakjes gebruiken om subquery's te maken, inclusief operators in de instructie tussen haakjes. zoekt bijvoorbeeld motel+(wifi|luxury) naar documenten met de term 'motel' en 'wifi' of 'luxe' (of beide).

Veldgroepering is vergelijkbaar, maar beperkt de groepering tot één veld. Zoekt bijvoorbeeld hotelAmenities:(gym+(wifi|pool)) in het veld 'hotelAmenities' naar 'gym' en 'wifi', of 'gym' en 'pool'.

Limieten voor querygrootte

Azure Cognitive Search legt limieten op voor querygrootte en -samenstelling, omdat niet-afhankelijke query's uw zoekservice kunnen ontwrichten. Er gelden limieten voor querygrootte en -samenstelling (het aantal componenten). Er bestaan ook limieten voor de lengte van het zoeken naar voorvoegsels en voor de complexiteit van het zoeken naar regex en jokertekens. Als uw toepassing programmatisch zoekquery's genereert, raden we u aan deze zo te ontwerpen dat er geen query's van niet-afhankelijke grootte worden gegenereerd.

Zie API-aanvraaglimieten voor meer informatie over querylimieten.

Zie ook