Lucene-querysyntaxis in Azure AI Search

  • Artikel

Bij het maken van query's in Azure AI Search kunt u kiezen voor de volledige Lucene Query Parser-syntaxis voor gespecialiseerde queryformulieren: jokertekens, fuzzy zoekopdrachten, nabijheid zoeken, reguliere expressies. Veel van de Lucene Query Parser-syntaxis wordt intact geïmplementeerd in Azure AI Search, met uitzondering van *bereikzoekopdrachten, die zijn samengesteld via $filter expressies.

Als u de volledige Lucene-syntaxis wilt gebruiken, stelt u het queryType in op full een queryexpressie die is gepatroont voor jokertekens, fuzzy zoekopdrachten of een van de andere queryformulieren die worden ondersteund door de volledige syntaxis. In REST worden query-expressies 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 velden en het stimuleren van termen. Het zoekt naar hotels waar het categorieveld de term budgetbevat. Documenten met de woordgroep "recently renovated" worden hoger gerangschikt als gevolg van de term boostwaarde (3).

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

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

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

Grondbeginselen van syntaxis

De volgende syntaxis fundamentals 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 alleen een ander teken in een tekenreeks.

In Lucene volledige syntaxis wordt de tilde (~) bijvoorbeeld gebruikt voor zowel fuzzy zoekopdrachten als nabijheidszoekopdrachten. Wanneer deze na een aanhalingsterm wordt geplaatst, ~ roept u nabijheidszoekopdrachten aan. Wanneer deze aan het einde van een term wordt geplaatst, ~ roept u fuzzy zoekopdrachten aan.

Binnen een term, zoals business~analyst, wordt het teken niet geëvalueerd als operator. In dit geval, ervan uitgaande dat de query een term of woordgroepsquery is, wordt de zoekfunctie voor volledige tekst met lexicale analyse de ~ term business~analyst in tweeën verbroken: business OF analyst.

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

Speciale tekens ontsnappen

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

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

Notitie

Hoewel het ontsnappen tokens bij elkaar houdt, kan lexicale analyse tijdens het indexeren ze verwijderen. De standaard Lucene-analyse breekt bijvoorbeeld woorden op afbreekstreepjes, witruimte en andere tekens. Als u speciale tekens in de querytekenreeks nodig hebt, hebt u mogelijk een analyse nodig die deze in de index bewaart. Sommige opties zijn onder andere Microsoft natuurlijke taalanalyses, die afbreekstreepjes bevatten, of een aangepaste analyse voor complexere patronen. Zie Gedeeltelijke termen, patronen en speciale tekens voor meer informatie.

Onveilige en gereserveerde tekens coderen in URL's

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

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

Booleaanse operators

U kunt Booleaanse operators insluiten in een querytekenreeks om de precisie van een overeenkomst te verbeteren. De volledige syntaxis ondersteunt tekstoperators naast tekenoperators. Geef altijd booleaanse tekstoperators (EN, OF, NIET) op in hoofdletters.

Tekstoperator Teken Opmerking Gebruik
EN + wifi AND luxury Hiermee geeft u termen op die een overeenkomst moet bevatten. In het voorbeeld zoekt de query-engine naar documenten met zowel wifi als luxury. Het plusteken (+) kan ook direct voor een term worden gebruikt om dit nodig 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 beide termen wordt gevonden. In het voorbeeld retourneert de query-engine overeenkomende documenten die een wifi of luxury beide bevatten. Omdat OR de standaardoperator voor combinaties is, kunt u deze ook weglaten, zodat dat wifi luxury het equivalent is van wifi OR luxury.
NIET !, - wifi –luxury Retourneert een overeenkomst op documenten die de term uitsluiten. Zoekt bijvoorbeeld wifi –luxury naar documenten met de wifi term maar niet luxury.

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

BOoleaanse operator NIET

Belangrijk

De OPERATOR NOT (NOT, !of -) gedraagt zich anders in volledige syntaxis dan in eenvoudige syntaxis.

  • In eenvoudige syntaxis hebben query's met negatie altijd automatisch een jokerteken toegevoegd. De query -luxury wordt bijvoorbeeld automatisch uitgebreid naar -luxury *.
  • In de volledige syntaxis kunnen query's met negatie niet worden gecombineerd met een jokerteken. De query's -luxury * zijn bijvoorbeeld niet toegestaan.
  • In de volledige syntaxis zijn query's met één negatie niet toegestaan. De query -luxury is bijvoorbeeld niet toegestaan.
  • In de volledige syntaxis gedragen negaties zich alsof ze altijd AND zijn op de query, ongeacht de zoekmodus.
    • De volledige syntaxisquery wifi -luxury in de volledige syntaxis haalt bijvoorbeeld alleen documenten op die de term wifibevatten en past vervolgens de negatie -luxury toe op die documenten.
  • Als u negaties wilt gebruiken om alle documenten in de index te doorzoeken, wordt een eenvoudige syntaxis met de any zoekmodus aanbevolen.
  • Als u negaties wilt gebruiken om te zoeken naar een subset documenten in de index, worden volledige syntaxis of de eenvoudige syntaxis met de volledige zoekmodus aanbevolen.
Querytype Zoekmodus Voorbeeldquery Gedrag
Eenvoudig willekeurige wifi -luxury Retourneert alle documenten in de index. Documenten met de term 'wifi' of documenten die de term 'luxe' missen, worden hoger gerangschikt dan andere documenten. De query wordt uitgebreid naar wifi OR -luxury OR *.
Eenvoudig Alles wifi -luxury Retourneert alleen documenten in de index die de term 'wifi' bevatten en die niet de term 'luxe' bevatten. De query wordt uitgebreid naar wifi AND -luxury AND *.
Volledig willekeurige wifi -luxury Retourneert alleen documenten in de index die de term 'wifi' bevatten en vervolgens worden documenten die de term 'luxe' bevatten, verwijderd uit de resultaten.
Volledig Alles wifi -luxury Retourneert alleen documenten in de index die de term 'wifi' bevatten en vervolgens worden documenten die de term 'luxe' bevatten, verwijderd uit de resultaten.

Zoeken in velden

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

  • genre:jazz NOT history

  • artists:("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 zoekt u naar twee afzonderlijke kunstenaars in het artists veld.

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

Notitie

Wanneer u zoekexpressies met velden gebruikt, hoeft u de searchFields parameter niet te gebruiken omdat voor elke zoekexpressie in een veld expliciet een veldnaam is opgegeven. U kunt de searchFields parameter echter nog steeds 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 met jazz het genre veld, terwijl deze overeenkomt NOT history met het description veld. De veldnaam die wordt opgegeven, 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 zoeken

Een fuzzy zoekopdracht vindt overeenkomsten in termen met een vergelijkbare constructie, waardoor een term wordt uitgebreid tot maximaal 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 tilde-symbool ~ aan het einde van één woord met een optionele parameter, een getal tussen 0 en 2 (standaard), waarmee de bewerkingsafstand wordt opgegeven. Bijvoorbeeld, blue~ of blue~1 retourneert blue, bluesen glue.

Fuzzy zoeken kan alleen worden toegepast op termen, niet tussen aanhalingstekens ingesloten woordgroepen, maar u kunt de tilde afzonderlijk toevoegen aan elke term in een naam of woordgroep met meerdere onderdelen. Zou bijvoorbeeld Unviersty~ of~ Wshington~ overeenkomen met University of Washington.

Nabijheidszoeken

Nabijheidszoekopdrachten worden gebruikt om termen te vinden die zich in de buurt van elkaar in een document bevinden. Voeg een tildesymbool ~ toe aan het einde van een woordgroep, gevolgd door het aantal woorden dat de nabijheidsgrens creëert. Zoekt bijvoorbeeld "hotel airport"~5 de termen hotel en airport binnen vijf woorden van elkaar in een document.

Termverbetering

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

In het volgende voorbeeld ziet u de verschillen. Stel dat er een scoreprofiel is dat overeenkomsten in een bepaald veld verhoogt, bijvoorbeeld genre in het voorbeeld van musicstoreindex. Termverhoging kan worden gebruikt om bepaalde zoektermen verder te verbeteren dan andere. Verhoogt bijvoorbeeld rock^2 electronic documenten die de zoektermen in het genreveld hoger bevatten dan andere doorzoekbare velden in de index. Verder worden documenten die de zoektermsteen bevatten, hoger gerangschikt dan de andere zoekterm elektronisch als gevolg van de waarde van de term boost (2).

Als u een term wilt verhogen, gebruikt u de caret, ^het symbool met een boostfactor (een getal) aan het einde van de term die u zoekt. U kunt ook zinnen stimuleren. 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

Een reguliere expressiezoekopdracht vindt een overeenkomst op basis van patronen die geldig zijn onder Apache Lucene, zoals beschreven in de RegExp-klasse. In Azure AI Search wordt een reguliere expressie tussen slashes /ingesloten.

Als u bijvoorbeeld documenten wilt zoeken met motel of hotel, geeft u op /[mh]otel/. Reguliere expressiezoekopdrachten worden vergeleken met enkele woorden.

Sommige hulpprogramma's en talen leggen extra escapetekenvereisten op buiten de escaperegels die door Azure AI Search worden opgelegd. Voor JSON worden tekenreeksen die een slash bevatten, met een schuine schuine streep naar achteren ge escaped: microsoft.com/azure/ hiermee wordt search=/.*microsoft.com\/azure\/.*/search=/.* <string-placeholder>.*/ de reguliere expressie ingesteld en microsoft.com\/azure\/ wordt de tekenreeks met een escaped slash weergegeven.

Twee veelvoorkomende symbolen in regex-query's zijn . en *. Een . teken komt overeen met één teken en een * komt overeen met het vorige teken nul of meer keren. Komt bijvoorbeeld /be./ overeen met de termen bee en bet de voorwaarden /be*/ komen overeen be, beemaar beee niet bet. Samen kunt .* u alle tekensreeksen vergelijken, zodat /be.*/ deze overeenkomen met een term die begint met be bijvoorbeeld better.

Als u syntaxisfouten krijgt in uw reguliere expressie, controleert u de escaperegels voor speciale tekens. U kunt ook een andere client proberen om te controleren of het probleem hulpprogrammaspecifiek is.

Zoeken met jokertekens

U kunt algemeen herkende syntaxis gebruiken voor zoekopdrachten met meerdere (*) of één (?) jokerteken. Volledige Lucene-syntaxis biedt ondersteuning voor voorvoegsel, invoegsel en achtervoegselkoppeling.

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

Type aanbrengen Beschrijving en voorbeelden
Voorvoegsel Termfragment komt voor * of ?. Bijvoorbeeld een query-expressie van search=alpha* retourneert alphanumeric of alphabetical. Het vergelijken van voorvoegsels wordt ondersteund in zowel eenvoudige als volledige syntaxis.
achtervoegsel Termfragment komt na * of ?, met een slash om de constructie te scheiden. Retourneert alphanumericbijvoorbeeld search=/.*numeric/ .
Infix Termfragmenten insluiten * of ?. Retourneert non-numerical bijvoorbeeld search=non*al en nonsensical.

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

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

Notitie

In de regel is patroonkoppeling traag, dus u kunt 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.

Effect 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 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 een analyse nodig tijdens het indexeren dat de integriteit van tekenreeksen behoudt, zodat gedeeltelijke term en patroonkoppeling slaagt. Zie Gedeeltelijke zoektermen in Azure AI Search-query's voor meer informatie.

Overweeg een situatie waarin u wilt dat de zoekquery terminal* resultaten retourneert die termen bevatten zoals terminate, terminationen terminates.

Als u de en.lucene -analyse (Engelse Lucene) zou gebruiken, zou het agressieve stemming van elke term toepassen. Bijvoorbeeld, terminateterminationterminates 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, dus er zouden 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. terminateBijvoorbeeld, terminates, en termination zal meestal geheel in de index blijven en zou een voorkeur zijn voor scenario's die veel afhankelijk zijn van jokertekens en fuzzy zoekopdrachten.

Scoren van jokertekens en regex-query's

Azure AI 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 genegeerd om te voorkomen dat de rangschikking aftekent op overeenkomsten van zeldzamere termen. Alle overeenkomsten worden evenzeer behandeld voor zoekopdrachten met jokertekens en regex-zoekopdrachten.

Speciale tekens

In sommige gevallen wilt u mogelijk 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. De standaardanalyse omzeilt veel speciale tekens, met uitzondering van uw index.

Analyzers die speciale tekens tokeniseren, bevatten de whitespace analyzer, waarbij rekening wordt gehouden met eventuele tekenreeksen gescheiden door witruimten als tokens (dus de ❤ tekenreeks wordt beschouwd als een token). Ook zou een taalanalyse zoals de Microsoft English Analyzer ('en.microsoft') de tekenreeks '€' als token gebruiken. U kunt een analyse testen om te zien welke tokens worden gegenereerd voor een bepaalde query.

Wanneer u Unicode-tekens gebruikt, moet u ervoor zorgen dat symbolen correct zijn ontsnapt in de query-URL (bijvoorbeeld voor ❤ het gebruik van de escape-reeks %E2%9D%A4+). Sommige REST-clients voeren deze vertaling automatisch uit.

Prioriteit (groeperen)

U kunt haakjes gebruiken om subquery's te maken, inclusief operators binnen de instructie haakjes. Zoekt bijvoorbeeld motel+(wifi|luxury) naar documenten met de motel term of wifiluxury (of beide).

Veldgroepering is vergelijkbaar, maar de groepering wordt beperkt 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 AI Search legt limieten op voor de querygrootte en -samenstelling, omdat niet-gebonden query's uw zoekservice kunnen stabiliseren. Er gelden limieten voor de querygrootte en samenstelling (het aantal componenten). Er bestaan ook limieten voor de lengte van het zoeken naar voorvoegsels en voor de complexiteit van regex-zoekopdrachten en zoekopdrachten met jokertekens. Als uw toepassing programmatisch zoekquery's genereert, raden we u aan deze zo te ontwerpen dat er geen query's met een niet-gebonden grootte worden gegenereerd.

Zie API-aanvraaglimieten voor meer informatie over querylimieten.

Zie ook