Sdílet prostřednictvím

Jednoduchá syntaxe dotazů ve službě Azure AI Search

Pro scénáře fulltextového vyhledávání azure AI Search implementuje dva dotazovací jazyky založené na Lucene, přičemž každý z nich je zarovnaný k analyzátoru dotazů. Analyzátor jednoduchých dotazů je výchozí. Řeší běžné případy použití a snaží se interpretovat požadavek, i když není dokonale složený. Další analyzátor je Lucene Query Parser a podporuje pokročilejší konstrukce dotazů.

Tento článek je referenčními informacemi o syntaxi dotazu pro jednoduchý analyzátor dotazů.

Syntaxe dotazu pro oba analyzátory se vztahuje na výrazy dotazu předávané v search parametru požadavku dotazu, ne zaměňovat se syntaxí OData s vlastní syntaxí a pravidly pro filter výrazy orderby ve stejném požadavku.

I když je jednoduchý analyzátor založený na třídě Apache Lucene Simple Query Parser , její implementace ve službě Azure AI Search vylučuje přibližné vyhledávání. Pokud potřebujete přibližné vyhledávání, zvažte místo toho alternativní úplnou syntaxi dotazu Lucene.

Příklad (jednoduchá syntaxe)

Tento příklad ukazuje jednoduchý dotaz rozlišující "queryType": "simple" a platnou syntaxi. I když je typ dotazu nastavený níže, jedná se o výchozí hodnotu, kterou je možné vynechat, pokud se nevrátíte z alternativního typu. Následující příklad je hledání nezávislých termínů s požadavkem, aby všechny odpovídající dokumenty obsahovaly "pool".

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

Parametr searchMode je v tomto příkladu relevantní. Vždy, když jsou v dotazu logické operátory, měli byste obecně nastavit searchMode=all , aby se zajistilo, že se shodují všechna kritéria. V opačném případě můžete použít výchozí nastavení searchMode=any , které upřednostňuje odvolání oproti přesnosti.

Další příklady najdete v příkladech syntaxe jednoduchých dotazů. Podrobnosti o požadavku a parametrech dotazu najdete v tématu Hledat dokumenty (REST API).

Hledání klíčových slov podle termínů a frází

Řetězce předané parametru search můžou obsahovat termíny nebo fráze v libovolném podporovaném jazyce, booleovských operátorů, operátory priority, zástupné znaky nebo znaky předpony pro dotazy typu "začíná", escape sekvence a znaky kódování adresy URL. Parametr search je volitelný. Nezadané, vyhledávání (search=* nebo search=" ") vrátí prvních 50 dokumentů v libovolném pořadí (bez pořadí).

  • Hledání termínů je dotaz jednoho nebo více termínů, kde se některý z termínů považuje za shodu.

  • Hledání frází pomocí vyhledávání je přesná fráze uzavřená do uvozovek " ". Když by například Roach Motel (bez uvozovek) vyhledaly dokumenty, které obsahují RoachMotel nebo kdekoli v libovolném pořadí, "Roach Motel" (s uvozovkami) se budou shodovat pouze s dokumenty, které obsahují celou frázi společně a v tomto pořadí (lexikální analýza stále platí).

V závislosti na vašem vyhledávacím klientovi může být nutné odlišit uvozovky v hledání frází. Například v požadavku POST může být vyhledávání frází "Roach Motel" v textu požadavku zadáno jako "\"Roach Motel\"". Pokud používáte sady Azure SDK, vyhledávací klient uniká uvozovky při serializaci hledaného textu. Vaše hledaná fráze může být odeslána jako "Roach Motel".

Ve výchozím nastavení všechny řetězce předané v parametru search procházejí lexikální analýzou. Ujistěte se, že rozumíte chování tokenizace analyzátoru, který používáte. Pokud jsou výsledky dotazů neočekávané, je často možné zjistit, jak se termíny v době dotazu tokenizují. Tokenizaci můžete otestovat u konkrétních řetězců , abyste potvrdili výstup.

Jakýkoli textový vstup s jedním nebo více termíny se považuje za platný výchozí bod pro provádění dotazu. Azure AI Search bude odpovídat dokumentům, které obsahují některé nebo všechny termíny, včetně všech variant nalezených během analýzy textu.

Ačkoli to zní jednoduše, existuje jeden aspekt vykonávání dotazů ve službě Azure AI Search, který může vést k neočekávaným výsledkům, což zvyšuje místo snižování výsledků hledání, protože do vstupního řetězce jsou přidávány další termíny a operátory. Zda k tomuto rozšíření skutečně dochází, závisí na zahrnutí operátoru NOT v kombinaci s nastavením parametru searchMode, který určuje, jak je NOT interpretován z pohledu chování AND nebo OR. Další informace naleznete v operátoru NOT v části Logické operátory.

Logické operátory

Logické operátory můžete vložit do řetězce dotazu, abyste zlepšili přesnost shody. V jednoduché syntaxi jsou logické operátory založené na znakech. Textové operátory, například slovo AND, nejsou podporované.

Znak Příklad Využití
+ pool + ocean Operace AND . Například stanoví, pool + ocean že dokument musí obsahovat oba termíny.
| pool | ocean Operace OR najde shodu, když se najde některý z termínů. V tomto příkladu dotazovací modul vrátí shodu u dokumentů obsahujících buď pool nebo ocean obojí. Vzhledem k tomu, že OR je výchozím operátorem spojení, můžete ho také vynechat, takže pool ocean je ekvivalentem k pool | ocean.
- pool – ocean NOT Operace vrátí výsledky u dokumentů, které daný termín vylučují.

Parametr searchMode dotazovacího požadavku určuje, zda je člen s operátorem NOTAND nebo OR s jinými členy v dotazu (za předpokladu, že neexistují žádné logické operátory v ostatních členech). Platné hodnoty zahrnují any nebo all.

searchMode=any zvyšuje zachycení dotazů zahrnutím dalších výsledků a defaultně se - interpretuje jako "OR NOT". Například pool - ocean odpovídá dokumentům, které buď obsahují termín pool, nebo neobsahují termín ocean.

searchMode=all zvýší přesnost dotazů tím, že zahrne méně výsledků a ve výchozím nastavení - se interpretuje jako "A NE". Například pomocí searchMode=any bude dotaz pool - ocean odpovídat dokumentům, které obsahují termín "bazén", a všem dokumentům, které neobsahují termín "oceán". To je pravděpodobně intuitivnější chování operátora - . Proto byste měli zvážit použití místo , pokud chcete optimalizovat hledání pro přesnost místo úplnosti, a vaši uživatelé často používají operátor při hledání.

Při rozhodování o searchMode nastavení zvažte vzory interakce uživatelů pro dotazy v různých aplikacích. Uživatelé, kteří hledají informace, pravděpodobně zahrnou do dotazu operátora, na rozdíl od e-commerce stránek, které mají více vestavěných navigačních struktur.

Dotazy předpon

U dotazů „začínající na“ přidejte operátor s příponou (*) jako zástupný symbol pro zbytek termínu. Před přidáním operátoru přípony musí dotaz předpony začínat alespoň jedním znakem prostého textu.

Znak Příklad Využití
* lingui* se bude shodovat s "lingvistikou" nebo "linguini" Hvězdička (*) představuje jeden nebo více znaků libovolné délky a nerozlišuje malá a velká písmena.

Podobně jako filtry hledá předponový dotaz přesnou shodu. Proto neexistuje žádné vyhodnocování relevance (všechny výsledky obdrží skóre hledání 1,0). Mějte na paměti, že dotazy na předpony mohou být pomalé, zejména pokud je index velký a předpona se skládá z malého počtu znaků. Alternativní metodologie, jako je například tokenizace n-gramu edge, může být rychlejší. Termíny používající vyhledávání předpon nesmí být delší než 1 000 znaků.

Jednoduchá syntaxe podporuje pouze porovnávání předpon. Pro suffixové nebo infixové párování na konci nebo uprostřed termínu použijte úplnou syntaxi Lucene pro vyhledávání se zástupnými znaky.

Uvolnění vyhledávacích operátorů

Operátory vyhledávání v jednoduché syntaxi obsahují tyto znaky: + | " ( ) ' \

Pokud některý z těchto znaků je součástí tokenu v indexu, uvozte ho předponou jediným zpětným lomítkem (\) v dotazu. Předpokládejme například, že jste použili vlastní analyzátor pro tokenizaci celého termínu a váš index obsahuje řetězec "Luxury+Hotel". Pokud chcete získat přesnou shodu s tímto tokenem, vložte escape sekvenci: search=luxury\+hotel.

Aby byly věci jednodušší pro typické případy, existují dvě výjimky z tohoto pravidla, kdy není potřeba escape sekvence.

  • Operátor - NOT musí být escapovaný pouze, pokud je prvním znakem za mezerou. Pokud se - zobrazí uprostřed (například v 3352CDD0-EF30-4A2E-A512-3B30AF40F3FD), můžete přeskočit jeho použití pro escapování.

  • Operátor přípony * musí být escapován pouze v případě, že je posledním znakem před mezerou. * Pokud se zobrazí uprostřed (například v 4*4=16), není potřeba žádné eskapace.

Poznámka:

Ve výchozím nastavení standardní analyzátor odstraní a přeruší slova u spojovníků, prázdných znaků, ampersandů a dalších znaků během lexikální analýzy. Pokud potřebujete, aby v řetězci dotazu zůstaly speciální znaky, budete možná potřebovat analyzátor, který je zachová v indexu. Mezi volby patří analyzátory jazyka Microsoft Natural, které zachovávají slova s dělením, nebo vlastní analyzátor pro složitější vzory. Další informace naleznete v části Částečné termíny, vzory a speciální znaky.

Kódování nebezpečných a rezervovaných znaků v adresách URL

Zajistěte, aby všechny nebezpečné a rezervované znaky byly kódovány v adrese URL. Znak #je například nebezpečný znak, protože se jedná o identifikátor fragmentu nebo ukotvení v adrese URL. Znak musí být kódován jako %23, pokud je použit v adrese URL. '&' a '=' jsou příklady vyhrazených znaků, protože oddělují parametry a určují hodnoty ve službě Azure AI Search. Další informace najdete v tématu RFC1738: Uniform Resource Locators (URL).

Nebezpečné znaky jsou " ` < > # % { } | \ ^ ~ [ ]. Rezervované znaky jsou ; / ? : @ = + &.

Speciální znaky

Speciální znaky můžou být v rozsahu od symbolů měny, jako je $nebo €, až po emoji. Mnoho analyzátorů, včetně výchozího standardního analyzátoru, vyloučí během indexování speciální znaky, což znamená, že v indexu nebudou reprezentovány.

Pokud potřebujete speciální reprezentaci znaků, můžete přiřadit analyzátor, který je zachová:

  • Analyzátor prázdných znaků považuje za tokeny libovolnou posloupnost znaků oddělenou prázdnými znaky (takže emoji ❤ "' by se považovalo za token).

  • Analyzátor jazyka, jako je například Microsoft English Analyzer (en.microsoft), by jako token vzal řetězec $nebo €.

Pro potvrzení můžete otestovat analyzátor , abyste zjistili, jaké tokeny se pro daný řetězec vygenerují. Jak můžete očekávat, nemusíte z jednoho analyzátoru získat úplnou tokenizaci. Alternativním řešením je vytvořit více polí, která obsahují stejný obsah, ale s různými přiřazeními analyzátoru (například description_en, description_fratd. pro analyzátory jazyka).

Pokud používáte znaky Unicode, ujistěte se, že jsou symboly v adrese URL dotazu správně escapované (například pro znak '❤' použijte sekvenci %E2%9D%A4+). Někteří weboví klienti tento překlad dělají automaticky.

Priorita (seskupení)

Můžete použít závorky k vytvoření poddotazů, které zahrnují operátory v rámci závorkového výrazu. Vyhledá například motel+(wifi|luxury) dokumenty obsahující termín "motel" a buď "wi-fi" nebo "luxury" (nebo obojí).

Omezení velikosti dotazů

Pokud vaše aplikace generuje vyhledávací dotazy prostřednictvím kódu programu, doporučujeme ho navrhnout tak, aby negenerovala dotazy s nevázanou velikostí.

  • V případě get nemůže délka adresy URL překročit 8 kB.

  • Pro POST (a jakýkoli jiný požadavek), kde text požadavku obsahuje search a další parametry, jako filterorderbya , maximální velikost je 16 MB. Mezi další omezení patří:

    • Maximální délka vyhledávací klauzule je 100 000 znaků.
    • Maximální počet klauzulí v search (výrazy oddělené operátorem AND nebo OR) je 1024.
    • Maximální velikost hledaného termínu je 1000 znaků pro hledání předpon.
    • Existuje také limit přibližně 32 kB velikosti libovolného jednotlivého termínu v dotazu.

Další informace o limitech dotazů najdete v tématu Omezení požadavků rozhraní API.

Další kroky

Pokud budete dotazy vytvářet programově, projděte si fulltextové vyhledávání ve službě Azure AI Search a seznamte se s fázemi zpracování dotazů a důsledky analýzy textu.

Další informace o konstrukci dotazů najdete také v následujících článcích:

  • Last updated on