Lucene-query syntaxis in Azure AI Zoeken

Bij het maken van query's in Azure AI Zoeken 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 Zoeken, met uitzondering van bereikzoekopdrachten, die worden samengesteld via $filter expressies.

Als u de volledige Lucene-syntaxis wilt gebruiken, stelt u het queryType in op full en voert u een query-expressie in die is gepatroond voor jokertekens, fuzzy-zoekopdrachten of een van de andere queryvormen 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. Dit specifieke voorbeeld toont zoeken op velden en het boosten van woordgroepen. Het zoekt naar hotels waar het categorieveld de term budgetbevat. Documenten met de woordgroep "recently renovated" krijgen extra gewicht en kunnen hoger worden gerangschikt als gevolg van de woordgroepsboostwaarde (3).

POST /indexes/hotels-sample/docs/search?api-version=2026-04-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 geciteerde zin wordt geplaatst, roept ~ nabijheidszoekopdracht aan. Wanneer deze aan het einde van een term wordt geplaatst, ~ roept fuzzy zoeken 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 volledige-tekstzoekopdracht met lexicale analyse verwijdert de ~ en splitst de term business~analyst in tweeën: business OR 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 zoekreeks, specificeert u bijvoorbeeld search=https\:\/\/*. Op dezelfde manier kan een escapetelefoonnummerpatroon er als volgt uitzien: \+1 \(800\) 642\-7676.

Speciale tekens die een escapesequentie vereisen, zijn onder andere:
+ - & | ! ( ) { } [ ] ^ " ~ * ? : \ /

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 Zoeken. 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 zoekopdracht 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.

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

BOoleaanse operator NIET

• 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 worden negaties behandeld alsof ze altijd aan de query worden toegevoegd met AND, 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.

Veld-gebaseerd zoeken

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.

Fuzzy zoekopdracht

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.

Nabijheid zoeken

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.

Termversterking

Beschouw zoeken als twee stappen. Eerst zoekt Azure AI Zoeken overeenkomende documenten. Vervolgens rangschikt het die overeenkomsten. Het boosten van termen heeft alleen invloed op de tweede stap: het kan documenten die overeenkomen met een deel van uw zoekopdracht hoger in de resultaten plaatsen.

Termverhoging verschilt van een scoreprofiel. Een boost geeft de voorkeur aan een woord, woordgroep of groep in de huidige query. Een scoreprofiel geeft voorkeur aan velden of andere indexinhoud volgens regels die in de index zijn gedefinieerd.

Bereik verhogen

Schrijf een caret (^) en een positief getal direct na het deel van de query waarvan u de voorkeur wilt geven. Bijvoorbeeld, tax^2 kan documenten die tax bevatten hoger plaatsen dan documenten die alleen overeenkomen met een niet-versterkte term. De standaardwaarde voor boost is 1. U kunt ook een waarde tussen 0 en 1 gebruiken, zoals 0.2, om een overeenkomst kleiner gewicht te geven.

De interpunctie geeft aan op welke woorden elke instructie betrekking heeft:

• Een veldnaam plus een dubbele punt, een veldprefix genoemd, verschijnt vóór een woord, een zinsnede tussen aanhalingstekens of een groep tussen haakjes. Geeft bijvoorbeeld content: aan Azure AI Zoeken om in het content veld te zoeken.
• Een boost, zoals ^2, verschijnt na een woord, een woordgroep tussen aanhalingstekens of een groep tussen haakjes. Het vertelt Azure AI Zoeken wat de voorkeur moet geven bij het rangschikking van de wedstrijden.

In de volgende tabel wordt de standaardwaarde searchMode=anygebruikt, waarbij een spatie tussen woorden werkt zoals OR.

Met searchMode=all vereist de zoekopdracht deferred tax^2 dat beide woorden overeenkomen. De boost is nog steeds alleen van toepassing op tax. Als u in plaats daarvan een van beide woorden wilt matchen, moet u deferred OR tax^2 schrijven.

Plaats de cursor na het afsluitende aanhalingsteken of haakje wanneer u de volledige woordgroep of groep wilt versterken. Haakjes vormen geen zinsdeel. Gebruik aanhalingstekens wanneer de woorden naast elkaar en in een specifieke volgorde moeten staan.

Boost en veldbereik

Een veldnaam gevolgd door een dubbele punt beperkt waar Azure AI Zoeken zoekt. Een boost verandert hoe Azure AI Zoeken een treffer rangschikt. U kunt beide gebruiken in dezelfde query.

Als dit bijvoorbeeld is ingesteld opsearchFields, zoekt de eerste query naar title in deferred en content intax.title De aanhalingstekens en haakjes in de andere query's houden beide woorden in content.

Effect van een analyzer op gebooste query’s

Voor gewone woorden, woordcombinaties en groepen woorden wordt tekstanalyse niet overgeslagen door boosting. Voordat er overeenkomsten worden gevonden, verwerkt Azure AI Zoeken de querytekst nog steeds met de analysefunctie van elk veld. Als gevolg hiervan kan dezelfde versterkte tekst anders overeenkomen in velden die gebruikmaken van verschillende analysen.

Een woordgroep of groep met een veldvoorvoegsel gebruikt de analyse van dat veld. Tekst zonder veldvoorvoegsel gebruikt de analyse voor elk veld dat wordt doorzocht. Als voorbeeld kan een analyzer die tekst omzet naar kleine letters, "DEFERRED TAX"^2 overeenkomen met in kleine letters geïndexeerde termen.

Andere queryformulieren, zoals jokertekens, reguliere expressies en fuzzy query's, gebruiken verschillende analyseregels. Als u een boost toevoegt, worden deze regels niet gewijzigd. Zie fase 2: Lexicale analyse voor meer informatie.

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 Zoeken is een reguliere expressie:

• Ingesloten tussen schuine strepen /
• Alleen kleine letters

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 Zoeken worden opgelegd. Voor JSON worden tekenreeksen die een slash bevatten met een backslash geëscaped: microsoft.com/azure/ wordt search=/.*microsoft.com\/azure\/.*/ waar search=/.* <string-placeholder>.*/ de reguliere expressie instelt, en microsoft.com\/azure\/ is de tekenreeks met een geëscapede slash.

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. Bijvoorbeeld, /be./ komt overeen met de termen bee en bet, terwijl /be*/ overeenkomt met be, bee, en beee maar niet met 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.

Wildcards zoeken

U kunt algemeen herkende syntaxis gebruiken voor zoekopdrachten met meerdere (*) of één (?) jokerteken. Volledige Lucene-syntaxis ondersteunt voorvoegsel en invoegselkoppeling. Gebruik de syntaxis van de reguliere expressie voor achtervoegselkoppeling.

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

U kunt operators in één expressie combineren. Komt bijvoorbeeld 980?2* overeen met 98072-1222 en 98052-1234, waarbij ? overeenkomt met een enkel verplicht teken en * overeenkomt met tekens van willekeurige lengte die volgen.

Achtervoegselmatching vereist de scheidingstekens schuine strepen / voor reguliere expressies. 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 * zich anders gedraagt wanneer het buiten regex-query's wordt gebruikt. Buiten het regex forward slash-scheidingsteken / is * een jokerteken en komt het overeen met een reeks tekens, vergelijkbaar met .* in regex. Als voorbeeld search=/non.*al/ produceert u dezelfde resultatenset als search=non*al.

Effect van een analyzer op jokertekenzoeken

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 tijdens het indexeren een analyzer nodig die de integriteit van tekenreeksen behoudt, zodat gedeeltelijke term- en patroonherkenning slagen. Zie voor meer informatie Gedeeltelijke zoektermen in Azure AI Zoeken-query's.

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

Als u de en.lucene-analyzer (Engelse Lucene) zou gebruiken, zou hij agressieve stamafleiding van iedere term toepassen. Bijvoorbeeld, terminate, termination, terminates zullen allemaal worden getokeniseerd 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. Bijvoorbeeld, terminate, terminates en termination zullen meestal geheel in de index blijven en zouden een voorkeur hebben voor scenario's die sterk afhankelijk zijn van jokertekens en fuzzy zoekopdrachten.

Beoordeling van jokertekens en regex-query's

Azure AI Zoeken 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 bevoordeelt bij 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 analyzer die u gebruikt, deze tekens niet wegfiltert. De standaard analyzer negeert veel speciale tekens, waardoor ze niet in uw index terechtkomen.

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 worden geëscapet in de query-URL (bijvoorbeeld voor ❤ zou u de escape-reeks %E2%9D%A4+ gebruiken). Sommige REST-clients voeren deze vertaling automatisch uit.

Prioriteit (groeperen)

Gebruik haakjes om te bepalen welke onderdelen van een query samen worden geëvalueerd. Bijvoorbeeld vereist motel AND (wifi OR luxury)motel en ten minste één van de termen tussen haakjes: wifi of luxury.

Plaats een veldvoorvoegsel vóór een haakje om die hele groep in één veld te doorzoeken. Bijvoorbeeld zoekt hotelAmenities:(wifi OR pool) alleen in het veld wifi naar pool of hotelAmenities.

Haakjes bepalen hoe AND en OR samenwerken. Ze vereisen geen woorden naast elkaar of in een specifieke volgorde. Gebruik aanhalingstekens voor dat gedrag. Als u een groep wilt stimuleren, plaatst u de caret na het haakje sluiten, zoals in hotelAmenities:(wifi OR pool)^2. Zie Boost-bereik voor meer informatie.

Limieten voor querygrootte

Azure AI Zoeken 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

• Queryvoorbeelden voor eenvoudige zoekopdrachten
• Queryvoorbeelden voor volledige Lucene-zoekopdracht
• documenten zoeken
• OData-expressiesyntaxis voor filters en sorteren
• Eenvoudige querysyntaxis in Azure AI Zoeken