Delen via

Eenvoudige querysyntaxis in Azure AI Search

  • Artikel

Voor zoekscenario's met volledige tekst implementeert Azure AI Search twee lucene-querytalen, die elk zijn uitgelijnd op een queryparser. De eenvoudige queryparser is de standaardinstelling. Het behandelt veelvoorkomende use cases en pogingen om een aanvraag te interpreteren, zelfs als deze niet perfect is samengesteld. De andere parser is Lucene Query Parser en ondersteunt geavanceerdere queryconstructies.

Dit artikel is de naslaginformatie over querysyntaxis voor de eenvoudige queryparser.

Querysyntaxis voor beide parsers is van toepassing op query-expressies die zijn doorgegeven in de search parameter van een queryaanvraag, niet te verwarren met de OData-syntaxis, met de eigen syntaxis en regels voor filter en orderby expressies in dezelfde aanvraag.

Hoewel de eenvoudige parser is gebaseerd op de Apache Lucene Simple Query Parser-klasse , sluit de implementatie in Azure AI Search fuzzy zoekopdrachten uit. Als u fuzzy zoekopdrachten nodig hebt, kunt u in plaats daarvan de alternatieve volledige Lucene-querysyntaxis overwegen.

Voorbeeld (eenvoudige syntaxis)

In dit voorbeeld ziet u een eenvoudige query, onderscheiden door "queryType": "simple" en geldige syntaxis. Hoewel het querytype hieronder is ingesteld, is dit de standaardinstelling en kan worden weggelaten, tenzij u een alternatief type gebruikt. Het volgende voorbeeld is een zoekopdracht op onafhankelijke termen, met een vereiste dat alle overeenkomende documenten 'pool' bevatten.

POST https://{{service-name}}.search.windows.net/indexes/hotel-rooms-sample/docs/search?api-version=2024-07-01
{
  "queryType": "simple",
  "search": "budget hotel +pool",
  "searchMode": "all"
}

De searchMode parameter is relevant in dit voorbeeld. Wanneer booleaanse operators zich in de query bevinden, moet u over het algemeen zo instellen searchMode=all dat alle criteria overeenkomen. Anders kunt u de standaardwaarde searchMode=any gebruiken die de voorkeur geeft aan relevante overeenkomsten over precisie.

Zie Voorbeelden van eenvoudige querysyntaxis voor meer voorbeelden. Zie Zoekdocumenten (REST API) voor meer informatie over de queryaanvraag en parameters.

Trefwoorden zoeken op termen en woordgroepen

Tekenreeksen die aan de search parameter worden doorgegeven, kunnen termen of woordgroepen bevatten in elke ondersteunde taal, booleaanse operatoren, operatoren voor prioriteit, jokertekens of voorvoegseltekens voor query's, escapetekens en URL-coderingstekens. De search parameter is optioneel. Niet opgegeven, zoekopdracht (search=* of search=" ") retourneert de top 50 documenten in willekeurige (niet-gerankte) volgorde.

  • Een zoekterm is een query van een of meer termen, waarbij een van de termen wordt beschouwd als een overeenkomst.

  • Een zoekterm is een exacte woordgroep tussen aanhalingstekens " ". Zo Roach Motel zoekt (zonder aanhalingstekens) naar documenten met Roach en/of Motel ergens in een willekeurige volgorde, "Roach Motel" (met aanhalingstekens) alleen documenten die die hele woordgroep samen bevatten en in die volgorde (lexicale analyse is nog steeds van toepassing).

Afhankelijk van uw zoekclient moet u mogelijk de aanhalingstekens in een woordgroepszoekopdracht ontsnappen. In een POST-aanvraag kan bijvoorbeeld een woordgroepszoekopdracht "Roach Motel" in de hoofdtekst van de aanvraag worden opgegeven als "\"Roach Motel\"". Als u de Azure SDK's gebruikt, ontsnapt de zoekclient aanhalingstekens wanneer de zoektekst wordt geserialiseerd. Uw zoekterm kan worden verzonden als 'Roach Motel'.

Standaard ondergaan alle tekenreeksen die zijn doorgegeven in de search parameter lexicale analyse. Zorg ervoor dat u het tokenisatiegedrag begrijpt van de analyse die u gebruikt. Wanneer queryresultaten onverwacht zijn, kan de reden vaak worden getraceerd naar de wijze waarop termen tijdens de query worden getokeniseerd. U kunt tokenisatie testen op specifieke tekenreeksen om de uitvoer te bevestigen.

Tekstinvoer met een of meer termen wordt beschouwd als een geldig startpunt voor het uitvoeren van query's. Azure AI Search komt overeen met documenten die een of alle termen bevatten, inclusief eventuele variaties die tijdens de analyse van de tekst zijn gevonden.

Net zo eenvoudig als dit klinkt, is er één aspect van het uitvoeren van query's in Azure AI Search dat onverwachte resultaten kan opleveren, waardoor de zoekresultaten toenemen in plaats van de zoekresultaten te verlagen naarmate er meer termen en operators worden toegevoegd aan de invoertekenreeks. Of deze uitbreiding daadwerkelijk plaatsvindt, is afhankelijk van de opname van een NOT-operator, gecombineerd met een searchMode parameterinstelling die bepaalt hoe NOT wordt geïnterpreteerd in termen van AND of OR gedrag. Zie de NOT operator onder Booleaanse operatoren voor meer informatie.

Booleaanse operators

U kunt Booleaanse operators insluiten in een querytekenreeks om de precisie van een overeenkomst te verbeteren. In de eenvoudige syntaxis zijn booleaanse operatoren gebaseerd op tekens. Tekstoperators, zoals het woord EN, worden niet ondersteund.

Teken Opmerking Gebruik
+ pool + ocean Een AND bewerking. Bepaalt bijvoorbeeld pool + ocean dat een document beide termen moet bevatten.
| pool | ocean Een OR bewerking vindt een overeenkomst wanneer een van beide termen wordt gevonden. In het voorbeeld retourneert de query-engine een overeenkomst op documenten die een pool of ocean beide bevatten. Omdat OR dit de standaardoperator voor combinaties is, kunt u deze ook weglaten, zodat dit pool ocean het equivalent is van pool | ocean.
- pool – ocean Een NOT bewerking retourneert overeenkomsten op documenten die de term uitsluiten.

De searchMode parameter voor een queryaanvraag bepaalt of een term met de NOT operator wordt ANDgeordeerd of ORmet andere termen in de query wordt gebruikt (ervan uitgaande dat er geen booleaanse operatoren zijn voor de andere termen). Geldige waarden zijn of any all.

searchMode=any verhoogt het intrekken van query's door meer resultaten op te nemen en wordt standaard - geïnterpreteerd als 'OR NOT'. Komt bijvoorbeeld pool - ocean overeen met documenten die de term pool bevatten of documenten die de term oceanniet bevatten.

searchMode=all verhoogt de precisie van query's door minder resultaten op te nemen en wordt standaard - geïnterpreteerd als 'AND NOT'. De query pool - ocean komt bijvoorbeeld overeen met searchMode=anydocumenten die de term 'pool' bevatten en alle documenten die de term 'oceaan' niet bevatten. Dit is waarschijnlijk een intuïtiever gedrag voor de - operator. Daarom moet u overwegen om te gebruiken searchMode=all in plaats van searchMode=any als u zoekopdrachten wilt optimaliseren voor precisie in plaats van relevante overeenkomsten, en uw gebruikers gebruiken de - operator vaak in zoekopdrachten.

Houd bij het bepalen van een searchMode instelling rekening met de gebruikersinteractiepatronen voor query's in verschillende toepassingen. Gebruikers die naar informatie zoeken, nemen waarschijnlijk een operator in een query op, in plaats van e-commercesites met ingebouwde navigatiestructuren.

Voorvoegselquery's

Voeg voor 'begint met'-query's een achtervoegseloperator (*) toe als tijdelijke aanduiding voor de rest van een term. Een voorvoegselquery moet beginnen met ten minste één alfanumerieke teken voordat u de operator voor achtervoegsel kunt toevoegen.

Teken Opmerking Gebruik
* lingui* komt overeen met "taalkundige" of "linguini" Het sterretje (*) vertegenwoordigt een of meer tekens van willekeurige lengte, waarbij hoofdletters en kleine letters worden genegeerd.

Net als bij filters zoekt een voorvoegselquery naar een exacte overeenkomst. Er is dus geen relevantiescore (alle resultaten ontvangen een zoekscore van 1,0). Houd er rekening mee dat voorvoegselquery's traag kunnen zijn, met name als de index groot is en het voorvoegsel uit een klein aantal tekens bestaat. Een alternatieve methodologie, zoals edge n-gram-tokenisatie, kan sneller worden uitgevoerd. Termen die zoeken met voorvoegsels gebruiken, mogen niet langer zijn dan 1000 tekens.

Eenvoudige syntaxis ondersteunt alleen overeenkomende voorvoegsels. Gebruik voor achtervoegsel of invoegsel dat overeenkomt met het einde of midden van een term de volledige Lucene-syntaxis voor zoeken met jokertekens.

Escape-zoekoperators

In de eenvoudige syntaxis bevatten zoekoperators de volgende tekens: + | " ( ) ' \

Als een van deze tekens deel uitmaakt van een token in de index, kunt u deze escapen door het voorvoegsel te voorzien van één backslash (\) in de query. Stel dat u een aangepaste analyse hebt gebruikt voor hele termentokenisatie en dat uw index de tekenreeks 'Luxury+Hotel' bevat. Als u een exacte overeenkomst op dit token wilt krijgen, voegt u een escape-teken in: search=luxury\+hotel.

Om dingen eenvoudig te maken voor de meer typische gevallen, zijn er twee uitzonderingen op deze regel waarbij escapen niet nodig is:

  • De operator - NOT hoeft alleen te worden ontsnapt als dit het eerste teken na een witruimte is. Als de afbeelding - in het midden wordt weergegeven (bijvoorbeeld in 3352CDD0-EF30-4A2E-A512-3B30AF40F3FD), kunt u ontsnappen overslaan.

  • De operator voor achtervoegsel * hoeft alleen te worden escaped als dit het laatste teken vóór een witruimte is. Als het * in het midden wordt weergegeven (bijvoorbeeld in 4*4=16), is er geen escape nodig.

Notitie

Standaard verwijdert en onderbreekt de standaardanalyse woorden op afbreekstreepjes, spaties, ampersands en andere tekens tijdens lexicale analyse. Als u speciale tekens nodig hebt om in de querytekenreeks te blijven staan, 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 wanneer ze parameters scheiden en waarden opgeven in Azure AI Search. Zie RFC1738: Uniform Resource Locators (URL)voor meer informatie.

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

Speciale tekens

Speciale tekens kunnen variëren van valutasymbolen, zoals $of €, tot emoji's. Veel analysefuncties, waaronder de standaardstandaardanalyse, sluiten speciale tekens uit tijdens het indexeren, wat betekent dat ze niet worden weergegeven in uw index.

Als u speciale tekenweergave nodig hebt, kunt u een analyse toewijzen die deze behoudt:

  • De whitespace analyzer beschouwt elke tekenreeks gescheiden door spaties als tokens (de emoji wordt dus ❤ beschouwd als een token).

  • Een taalanalyse, zoals de Microsoft English Analyzer (en.microsoft), neemt de tekenreeks '$' of '€' als een token.

Ter bevestiging kunt u een analyse testen om te zien welke tokens voor een bepaalde tekenreeks worden gegenereerd. Zoals u zou verwachten, krijgt u mogelijk geen volledige tokenisatie van één analyse. Een tijdelijke oplossing is het maken van meerdere velden die dezelfde inhoud bevatten, maar met verschillende analysetoewijzingen (bijvoorbeeld description_en, description_frenzovoort voor taalanalyses).

Wanneer u Unicode-tekens gebruikt, moet u ervoor zorgen dat symbolen correct zijn ontsnapt in de query-URL (bijvoorbeeld voor '❤' wordt de escapereeks %E2%9D%A4+gebruikt). Sommige webclients 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 term 'motel' en 'wifi' of 'luxe' (of beide).

Limieten voor querygrootte

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.

  • Voor GET mag de lengte van de URL niet groter zijn dan 8 kB.

  • Voor POST (en elke andere aanvraag), waarbij de hoofdtekst van de aanvraag bevat search en andere parameters zoals filter en orderby, is de maximale grootte 16 MB. Aanvullende limieten zijn onder andere:

    • De maximale lengte van de zoekcomponent is 100.000 tekens.
    • Het maximum aantal componenten in search (expressies gescheiden door AND of OR) is 1024.
    • De maximale zoektermgrootte is 1000 tekens voor het zoeken naar voorvoegsels.
    • Er geldt ook een limiet van ongeveer 32 kB voor de grootte van een afzonderlijke term in een query.

Zie API-aanvraaglimieten voor meer informatie over querylimieten.

Volgende stappen

Als u programmatisch query's maakt, bekijkt u zoeken in volledige tekst in Azure AI Search om inzicht te krijgen in de fasen van het verwerken van query's en de gevolgen van tekstanalyse.

U kunt ook de volgende artikelen bekijken voor meer informatie over het bouwen van query's: