Een volledige-tekstquery maken in Azure AI Search

Als u een query bouwt voor zoeken in volledige tekst, bevat dit artikel de stappen voor het instellen van de aanvraag. Er wordt ook een querystructuur geïntroduceerd en wordt uitgelegd hoe veldkenmerken en taalkundige analysen van invloed kunnen zijn op queryresultaten.

Vereisten

Een Azure AI Search-service (een willekeurige laag). Maak een service of zoek een bestaande service.
Een zoekindex met tekenreeksvelden die zijn toegeschreven als doorzoekbaar. U kunt ook een indexalias gebruiken als het eindpunt van uw queryaanvraag.
Machtigingen om een query uit te voeren op de index:
- Verificatie op basis van sleutels: een query-API-sleutel voor uw zoekservice.
- Verificatie op basis van rollen: de rol Search Index Data Reader .
Installeer voor SDK-ontwikkeling de Azure Search-clientbibliotheek:
- Python: azure-search-documents
- .NET: Azure.Search.Documents
- JavaScript: @azure/search-documents
- Java: azure-search-documents

Aanbeveling

Ga voor een snel codevoorbeeld naar Voorbeeld van een volledige tekstquery.

Voorbeeld van een queryaanvraag in volledige tekst

In Azure AI Search is een query een alleen-lezenaanvraag voor de docs-verzameling van één zoekindex, met parameters die de uitvoering van query's informeren en het antwoord vormgeven dat terugkomt.

Een volledige tekstquery wordt opgegeven in een search parameter en bestaat uit termen, tussen aanhalingstekens en operatoren. Andere parameters voegen meer definitie toe aan de aanvraag.

De volgende aanroep van de REST API van Search POST illustreert een queryaanvraag met behulp van search en andere parameters.

POST https://[service name].search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2025-09-01
{
    "search": "NY +view",
    "queryType": "simple",
    "searchMode": "all",
    "searchFields": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "select": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "top": 10,
    "count": true
}

Naslaginformatie:POST zoeken

Belangrijkste punten

search biedt de criteria voor overeenkomsten, meestal hele termen of woordgroepen, met of zonder operatoren. Elk veld dat wordt toegeschreven als doorzoekbaar in het indexschema, valt binnen het bereik van een zoekbewerking.
queryType stelt de parser in: eenvoudig, vol. De standaard eenvoudige queryparser is optimaal voor zoeken in volledige tekst. De volledige Lucene-queryparser is bedoeld voor geavanceerde queryconstructies zoals reguliere expressies, nabijheid zoeken, fuzzy en jokertekens zoeken. Deze parameter kan ook worden ingesteld op semantisch voor semantische classificatie voor geavanceerde semantische modellering in het queryantwoord.
searchMode geeft aan of overeenkomsten zijn gebaseerd op alle criteria (voorkeursnauwkeurigheid) of criteria (voorkeur intrekken) in de expressie. De standaardwaarde is willekeurige. Als u verwacht dat booleaanse operatoren intensief worden gebruikt, wat waarschijnlijker is in indexen die grote tekstblokken bevatten (een inhoudsveld of lange beschrijvingen), moet u query's testen met de searchMode=Any|All parameter om de impact van die instelling op booleaanse zoekopdrachten te evalueren.
searchFields beperkt de uitvoering van query's tot specifieke doorzoekbare velden. Tijdens de ontwikkeling is het handig om dezelfde lijst met velden te gebruiken voor selecteren en zoeken. Anders is een overeenkomst mogelijk gebaseerd op veldwaarden die u niet in de resultaten kunt zien, waardoor er onzekerheid ontstaat over de reden waarom het document is geretourneerd.

Parameters die worden gebruikt om het antwoord vorm te geven:

select geeft aan welke velden moeten worden geretourneerd in het antwoord. Alleen velden die zijn gemarkeerd als ophaalbaar in de index, kunnen worden gebruikt in een select-instructie.
top retourneert het opgegeven aantal best overeenkomende documenten. In dit voorbeeld worden slechts 10 treffers geretourneerd. U kunt de resultaten bovenaan gebruiken en overslaan (niet weergegeven).
count geeft aan hoeveel documenten in de hele index in het algemeen overeenkomen, wat meer kan zijn dan wat wordt geretourneerd. Geldige waarden zijn 'true' of 'false'. De standaardwaarde is 'false'. Aantal is nauwkeurig als de index stabiel is, maar bij documenten die actief worden toegevoegd, bijgewerkt of verwijderd, kan het aantal onder- of overgerapporteerd worden. Als u alleen het aantal zonder documenten wilt ophalen, kunt u $top=0 gebruiken.
orderby wordt gebruikt als u resultaten wilt sorteren op een waarde, zoals een classificatie of locatie. Anders wordt de relevantiescore standaard gebruikt om resultaten te rangschikken. Een veld moet worden toegeschreven als sorteerbaar als kandidaat voor deze parameter.

Een client kiezen

Voor vroege ontwikkeling en proof-of-concept testen begint u met Azure Portal of een REST-client of een Jupyter-notebook. Deze benaderingen zijn interactief, handig voor gerichte tests en helpen u bij het beoordelen van de effecten van verschillende eigenschappen zonder dat u code hoeft te schrijven.

Als u zoeken vanuit een app wilt aanroepen, gebruikt u de Azure.Document.Search clientbibliotheken in de Azure SDK's voor .NET, Java, JavaScript en Python.

Wanneer u een index opent, kunt u in Azure Portal samen met Search Explorer naast de JSON-indexdefinitie naast de indextabbladen werken voor eenvoudige toegang tot veldkenmerken. Controleer de tabel Velden om te zien welke doorzoekbaar, sorteerbaar, filterbaar en facetable zijn tijdens het testen van query's.

Meld u aan bij Azure Portal en zoek uw zoekservice.
Selecteer Indexen in uw service en kies een index.
Er wordt een index geopend op het tabblad Search Explorer , zodat u direct query's kunt uitvoeren. Schakel over naar de JSON-weergave om de querysyntaxis op te geven.

Hier volgt een zoekquery-expressie voor volledige tekst die werkt voor de voorbeeldindex Hotels:
```
   {
       "search": "pool spa +airport",
       "queryType": "simple",
       "searchMode": "any",
       "searchFields": "Description, Tags",
       "select": "HotelName, Description, Tags",
       "top": 10,
       "count": true
   }
```
Naslaginformatie:POST zoeken

In de volgende schermopname ziet u de query en het antwoord:

Wanneer de aanvraag-URL wordt aangeroepen met GET, mag de lengte van de aanvraag-URL niet groter zijn dan 8 kB. Deze lengte is voldoende voor de meeste toepassingen. Sommige toepassingen produceren echter grote query's, met name wanneer OData-filterexpressies worden gebruikt. Voor deze toepassingen is HTTP POST een betere keuze omdat het grotere filters toestaat dan GET.

Met POST is het aantal componenten in een filter de beperkende factor, niet de grootte van de onbewerkte filtertekenreeks, omdat de aanvraaggroottelimiet voor POST ongeveer 16 MB is. Hoewel de limiet voor de POST-aanvraaggrootte groot is, kunnen filterexpressies niet willekeurig complex zijn. Zie OData Expression Syntaxis voor meer informatie over beperkingen voor filtercomplexiteit.

Gebruik een REST-client om een aanvraag in te stellen. Als u hulp nodig hebt bij het aan de slag gaan, raadpleegt u snelstartgids: Zoeken in volledige tekst met REST.

In het volgende voorbeeld wordt de REST API aangeroepen voor zoeken in volledige tekst:

POST https://[service name].search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2025-09-01
{
    "search": "NY +view",
    "queryType": "simple",
    "searchMode": "all",
    "searchFields": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "select": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "count": true
}

Naslaginformatie:Zoeken naar POST

Vervolg van gedeeltelijke zoekopdrachten

Soms kan Azure AI Search niet alle aangevraagde resultaten retourneren in één search-antwoord. Een gedeeltelijke reactie kan om verschillende redenen optreden, bijvoorbeeld wanneer de query te veel documenten retourneert door geen $top op te geven of door een waarde op te geven voor $ top die te groot is. In dergelijke gevallen bevat Azure AI Search de @odata.nextLink aantekening in de hoofdtekst van het antwoord en ook @search.nextPageParameters als het een POST-aanvraag was. U kunt de waarden van deze aantekeningen gebruiken om een andere zoekopdracht te formuleren om het volgende deel van het zoekantwoord op te halen. Dit gedrag wordt een vervolg van de oorspronkelijke zoekaanvraag genoemd en de aantekeningen worden vervolgtokens genoemd. Zie het voorbeeld in de sectie Antwoord voor meer informatie over de syntaxis van deze aantekeningen en waar deze worden weergegeven in de hoofdtekst van het antwoord.

De redenen waarom Azure AI Search vervolgtokens kan retourneren, zijn implementatiespecifiek en kunnen worden gewijzigd. Robuuste clients moeten altijd klaar zijn om gevallen af te handelen waarin minder documenten worden geretourneerd dan verwacht en een vervolgtoken wordt meegestuurd om door te gaan met het ophalen van documenten. Houd er ook rekening mee dat u dezelfde HTTP-methode moet gebruiken als de oorspronkelijke aanvraag om door te gaan. Als u bijvoorbeeld een GET-aanvraag hebt verzonden, moeten alle vervolgaanvragen die u verzendt ook GET gebruiken (en ook voor POST).

Opmerking

Het doel van @odata.nextLink en @search.nextPageParameters is om de service te beschermen tegen query's die te veel resultaten aanvragen, niet om een algemeen mechanisme voor paging te bieden. Als u resultaten wilt bekijken, gebruikt u $top en $skip samen. Als u bijvoorbeeld pagina's van grootte 10 wilt, moet uw eerste aanvraag $top=10 en $skip=0 hebben, moet de tweede aanvraag $top=10 en $skip=10 hebben, moet de derde aanvraag $top=10 en $skip=20 hebben, enzovoort.

In de volgende voorbeelden ziet u hoe u een volledige-tekstquery uitvoert met behulp van de Azure SDK's.

Python

from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient

# Set up the client
service_name = "<your-search-service-name>"
index_name = "hotels-sample-index"
api_key = "<your-query-api-key>"

endpoint = f"https://{service_name}.search.windows.net"
credential = AzureKeyCredential(api_key)
client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)

# Run a full-text search query
results = client.search(
    search_text="NY +view",
    search_mode="all",
    search_fields=["HotelName", "Description", "Address/City", "Tags"],
    select=["HotelName", "Description", "Address/City", "Tags"],
    top=10,
    include_total_count=True
)

print(f"Total documents matching query: {results.get_count()}")
for result in results:
    print(f"Hotel: {result['HotelName']}")

Naslaginformatie:SearchClient, zoeken

C#

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Models;

// Set up the client
string serviceName = "<your-search-service-name>";
string indexName = "hotels-sample-index";
string apiKey = "<your-query-api-key>";

Uri endpoint = new Uri($"https://{serviceName}.search.windows.net");
AzureKeyCredential credential = new AzureKeyCredential(apiKey);
SearchClient searchClient = new SearchClient(endpoint, indexName, credential);

// Run a full-text search query
SearchOptions options = new SearchOptions
{
    SearchMode = SearchMode.All,
    IncludeTotalCount = true,
    Size = 10
};
options.SearchFields.Add("HotelName");
options.SearchFields.Add("Description");
options.Select.Add("HotelName");
options.Select.Add("Description");

SearchResults<SearchDocument> response = await searchClient.SearchAsync<SearchDocument>("NY +view", options);

Console.WriteLine($"Total documents matching query: {response.TotalCount}");
await foreach (SearchResult<SearchDocument> result in response.GetResultsAsync())
{
    Console.WriteLine($"Hotel: {result.Document["HotelName"]}");
}

Naslaginformatie:SearchClient, SearchAsync, SearchOptions

Aanvullende SDK-resources

Azure SDK	Klant	Voorbeelden
.NET	SearchClient	DotNetHowTo
Java	SearchClient	SearchForDynamicDocumentsExample.java
JavaScript	SearchClient	SDK-voorbeelden
Python	SearchClient	sample_simple_query.py

Kies een querytype: eenvoudig | vol

Als uw query zoeken in volledige tekst is, wordt een queryparser gebruikt voor het verwerken van tekst die wordt doorgegeven als zoektermen en woordgroepen. Azure AI Search biedt twee queryparsers.

De eenvoudige parser begrijpt de eenvoudige querysyntaxis. Deze parser is geselecteerd als de standaardinstelling voor de snelheid en effectiviteit in vrije tekstquery's. De syntaxis ondersteunt veelgebruikte zoekoperators (EN, OF, NIET) voor zoektermen en woordgroepen, en voorvoegsel () zoeken (*zoals in sea* seattle en kust). Een algemene aanbeveling is om eerst de eenvoudige parser uit te proberen en vervolgens door te gaan naar de volledige parser als toepassingsvereisten vragen om krachtigere query's.
De volledige Lucene-querysyntaxis, ingeschakeld wanneer u aan de aanvraag toevoegt queryType=full , is gebaseerd op de Apache Lucene Parser.

Volledige syntaxis en eenvoudige syntaxis overlappen voor zover beide hetzelfde voorvoegsel en booleaanse bewerkingen ondersteunen, maar de volledige syntaxis biedt meer operators. Volledig zijn er meer operators voor Boole-expressies en meer operators voor geavanceerde query's, zoals fuzzy zoeken, zoeken met jokertekens, nabijheidszoekopdrachten en reguliere expressies.

Querymethoden kiezen

Zoeken is in wezen een gebruikersgestuurde oefening, waarbij termen of woordgroepen worden verzameld uit een zoekvak of van klikgebeurtenissen op een pagina. De volgende tabel bevat een overzicht van de mechanismen waarmee u gebruikersinvoer kunt verzamelen, samen met de verwachte zoekervaring.

Invoer	Ervaring
Zoekmethode	Een gebruiker typt de termen of woordgroepen in een zoekvak, met of zonder operators, en selecteert Zoeken om de aanvraag te verzenden. Zoeken kan worden gebruikt met filters voor dezelfde aanvraag, maar niet met automatisch aanvullen of suggesties.
Methode Automatisch aanvullen	Een gebruiker typt een paar tekens en query's worden gestart nadat elk nieuw teken is getypt. Het antwoord is een voltooide tekenreeks uit de index. Als de opgegeven tekenreeks geldig is, selecteert de gebruiker Zoeken om die query naar de service te verzenden.
Methode Suggesties	Net als bij automatisch aanvullen worden een gebruiker een paar tekens en incrementele query's gegenereerd. Het antwoord is een vervolgkeuzelijst met overeenkomende documenten, meestal vertegenwoordigd door enkele unieke of beschrijvende velden. Als een van de selecties geldig is, selecteert de gebruiker er een en wordt het overeenkomende document geretourneerd.
Facetnavigatie	Een pagina toont klikbare navigatiekoppelingen of breadcrumbs die het bereik van de zoekopdracht beperken. Een facetnavigatiestructuur is dynamisch samengesteld op basis van een eerste query. Als u bijvoorbeeld `search=*` een facetnavigatiestructuur wilt vullen die bestaat uit elke mogelijke categorie. Er wordt een facetnavigatiestructuur gemaakt op basis van een queryantwoord, maar het is ook een mechanisme voor het uitdrukken van de volgende query. n REST API-verwijzing, `facets` wordt gedocumenteerd als een queryparameter van een bewerking Documenten zoeken, maar kan worden gebruikt zonder de `search` parameter.
Filtermethode	Filters worden gebruikt met facetten om de resultaten te beperken. U kunt ook een filter achter de pagina implementeren, bijvoorbeeld om de pagina te initialiseren met taalspecifieke velden. In REST API-verwijzing `$filter` wordt beschreven als een queryparameter van een bewerking Documenten zoeken, maar kan deze worden gebruikt zonder de `search` parameter.

Effect van veldkenmerken op query's

Als u bekend bent met querytypen en -samenstelling, weet u misschien dat de parameters voor een queryaanvraag afhankelijk zijn van veldkenmerken in een index. Zo kunnen alleen velden die als doorzoekbaar en ophaalbaar zijn gemarkeerd, worden gebruikt in query's en zoekresultaten. Wanneer u de searchparameters filteren orderby parameters in uw aanvraag instelt, moet u de kenmerken controleren om onverwachte resultaten te voorkomen.

In de volgende schermopname van de voorbeeldindex hotels zijn alleen de laatste twee velden LastRenovationDate en Rating sorteerbaar, een vereiste voor gebruik in een "$orderby" enige component.

Zie Index maken (REST API) voor veldkenmerkdefinities.

Effect van tokens op query's

Tijdens het indexeren gebruikt de zoekmachine een tekstanalyse op tekenreeksen om het potentieel voor het vinden van een overeenkomst tijdens de query te maximaliseren. Tekenreeksen zijn minimaal kleine letters, maar afhankelijk van de analyse kunnen ook lemmatisatie ondergaan en het verwijderen van woorden stoppen. Grotere tekenreeksen of samengestelde woorden worden meestal opgesplitst door spaties, afbreekstreepjes of streepjes en geïndexeerd als afzonderlijke tokens.

Het belangrijkste punt is dat wat u denkt dat uw index bevat en wat er daadwerkelijk in zit, anders kan zijn. Als query's geen verwachte resultaten retourneren, kunt u de tokens inspecteren die door de analyse zijn gemaakt via de Analysetekst (REST API). Zie Gedeeltelijke zoektermen en patronen met speciale tekens voor meer informatie over tokenisatie en het effect op query's.

Queryproblemen oplossen

De volgende tabel bevat veelvoorkomende queryproblemen en hoe u deze kunt oplossen.

Probleem	Oorzaak	Resolutie / Besluit
Lege resultaten	Er zijn geen documenten die overeenkomen met querytermen.	Controleer of het veld is gemarkeerd als doorzoekbaar in het schema. Gebruik de Analysetekst-API om tokenisatie te controleren.
Onverwachte resultaten	Query komt overeen met niet bedoelde velden.	Gebruik `searchFields` dit om te beperken welke velden worden doorzocht.
Te veel resultaten	De zoekopdracht is te breed.	Voeg filters toe, gebruik `searchMode=all`of voeg vereiste termen toe met `+` de operator.
Resultaten niet gerangschikt zoals verwacht	Scoren op relevantie komt niet overeen met verwachtingen.	Overweeg het scoren van profielen of semantische classificatie.
Gedeeltelijke overeenkomsten ontbreken	De tokenizer tokeniseerde anders dan verwacht.	Gebruik een jokertekensuffix (`*`) of controleer het analysegedrag met de Analyze Text API.
Filter werkt niet	Veld is niet gemarkeerd als filterbaar.	Indexschema bijwerken om `filterable: true` op het veld in te stellen.

Nu u een beter inzicht hebt in hoe queryaanvragen werken, kunt u de volgende quickstarts uitproberen voor praktische ervaring.

Feedback

Is deze pagina nuttig?

Last updated on 2026-01-22