Azure Bilişsel Arama arama sonuçlarıyla çalışmaHow to work with search results in Azure Cognitive Search

Bu makalede, toplam eşleşen belge sayısı, sayfalandırılmış sonuçlar, sıralanmış sonuçlar ve isabet vurgulu terimler ile geri gelen bir sorgu yanıtının nasıl alınacağı açıklanmaktadır.This article explains how to get a query response that comes back with a total count of matching documents, paginated results, sorted results, and hit-highlighted terms.

Bir yanıtın yapısı, sorgudaki parametrelere göre belirlenir: REST API veya .NET SDK 'da Documentsearchresult sınıfında Arama belgesi .The structure of a response is determined by parameters in the query: Search Document in the REST API, or DocumentSearchResult Class in the .NET SDK.

Sonuç oluşturmaResult composition

Bir arama belgesi çok sayıda alandan oluşabilir, genellikle sonuç kümesindeki her bir belgeyi temsil etmek için yalnızca birkaç tane gerekir.While a search document might consist of a large number of fields, typically only a few are needed to represent each document in the result set. Bir sorgu isteğinde, $select=<field list> yanıtta hangi alanların gösterileceğini belirtmek için sonuna ekleyin.On a query request, append $select=<field list> to specify which fields show up in the response. Bir alan, bir sonuca dahil edilecek dizinde alınabilir olarak belirtilmelidir.A field must be attributed as Retrievable in the index to be included in a result.

En iyi şekilde çalışan alanlar, Kullanıcı bölümünde bir tıklama yanıtı davet etmek için yeterli bilgi sağlayan ve belgeler arasında ayrım yapan ve bunları ayırt eden alanlardır.Fields that work best include those that contrast and differentiate among documents, providing sufficient information to invite a click-through response on the part of the user. Bir e-ticaret sitesinde bir ürün adı, açıklama, marka, renk, boyut, Fiyat ve derecelendirme olabilir.On an e-commerce site, it might be a product name, description, brand, color, size, price, and rating. Oteller-örnek dizini yerleşik örneği için aşağıdaki örnekteki alanlar olabilir:For the hotels-sample-index built-in sample, it might be fields in the following example:

POST /indexes/hotels-sample-index/docs/search?api-version=2020-06-30 
    {  
      "search": "sandy beaches",
      "select": "HotelId, HotelName, Description, Rating, Address/City"
      "count": true
    }

Not

Görüntü dosyalarını bir ürün fotoğrafı veya logosu gibi bir sonuca eklemek istiyorsanız, bunları Azure Bilişsel Arama dışında depolayın, ancak arama belgesinde görüntü URL 'sine başvurmak için dizininizdeki bir alanı ekleyin.If want to include image files in a result, such as a product photo or logo, store them outside of Azure Cognitive Search, but include a field in your index to reference the image URL in the search document. Sonuçlarda görüntüleri destekleyen örnek dizinler, bu hızlıbaşlangıçta sunulan reatastate-Sample-US tanıtımı ve New York City işleri tanıtım uygulaması' nı içerir.Sample indexes that support images in the results include the realestate-sample-us demo, featured in this quickstart, and the New York City Jobs demo app.

Disk belleği sonuçlarıPaging results

Varsayılan olarak, arama altyapısı, sorgu tam metin aramasında veya tam eşleştirme sorguları için rastgele bir düzende, arama puanı tarafından belirlendiği şekilde ilk 50 eşleştirmeye kadar geri döner.By default, the search engine returns up to the first 50 matches, as determined by search score if the query is full text search, or in an arbitrary order for exact match queries.

Farklı sayıda eşleşen belge döndürmek için $top $skip sorgu isteğine ve parametreleri ekleyin.To return a different number of matching documents, add $top and $skip parameters to the query request. Aşağıdaki listede Logic açıklanmaktadır.The following list explains the logic.

  • $count=trueBir dizin içindeki toplam eşleşen belge sayısının sayısını almak için ekleyin.Add $count=true to get a count of the total number of matching documents within an index.

  • İlk 15 eşleşen belge kümesini ve toplam eşleşme sayısını döndürün: GET /indexes/<INDEX-NAME>/docs?search=<QUERY STRING>&$top=15&$skip=0&$count=trueReturn the first set of 15 matching documents plus a count of total matches: GET /indexes/<INDEX-NAME>/docs?search=<QUERY STRING>&$top=15&$skip=0&$count=true

  • İkinci kümeyi döndürün, sonraki 15 ' i almak için ilk 15 ' i atlayarak: $top=15&$skip=15 .Return the second set, skipping the first 15 to get the next 15: $top=15&$skip=15. Üçüncü 15 kümesi için aynısını yapın: $top=15&$skip=30Do the same for the third set of 15: $top=15&$skip=30

Temel alınan dizin değiştirilirken sayfalandırılmış sorguların sonuçlarının kararlı olmaması garanti edilmez.The results of paginated queries are not guaranteed to be stable if the underlying index is changing. Sayfalama $skip , her bir sayfa için değerini değiştirir, ancak her sorgu bağımsızdır ve sorgu zamanında dizinde olduğu gibi verilerin geçerli görünümü üzerinde çalışır (başka bir deyişle, bir genel amaçlı veritabanında bulunanlar gibi, sonuçların önbelleğe alınması veya anlık görüntüsü yoktur).Paging changes the value of $skip for each page, but each query is independent and operates on the current view of the data as it exists in the index at query time (in other words, there is no caching or snapshot of results, such as those found in a general purpose database).   Yinelemeleri nasıl alabileceğiniz hakkında bir örnek aşağıda verilmiştir.Following is an example of how you might get duplicates. Dört belge içeren bir dizin varsayın:Assume an index with four documents:

{ "id": "1", "rating": 5 }
{ "id": "2", "rating": 3 }
{ "id": "3", "rating": 2 }
{ "id": "4", "rating": 1 }

  Şimdi sonuçların, derecelendirmeye göre sıralanmış olarak her seferinde bir kez döndürülmesini istediğinizi varsayın.Now assume you want results returned two at a time, ordered by rating. Sonuçların ilk sayfasını almak için bu sorguyu yürütülecektir: $top=2&$skip=0&$orderby=rating desc , aşağıdaki sonuçları üretir:You would execute this query to get the first page of results: $top=2&$skip=0&$orderby=rating desc, producing the following results:

{ "id": "1", "rating": 5 }
{ "id": "2", "rating": 3 }

  Hizmette, sorgu çağrıları arasındaki dizine beşinci bir belge eklendiğini varsayalım: { "id": "5", "rating": 4 } .On the service, assume a fifth document is added to the index in between query calls: { "id": "5", "rating": 4 }. Kısa süre sonra, ikinci sayfayı getirmek için bir sorgu yürütüyoruz $top=2&$skip=2&$orderby=rating desc ve şu sonuçları elde edersiniz:Shortly thereafter, you execute a query to fetch the second page: $top=2&$skip=2&$orderby=rating desc, and get these results:

{ "id": "2", "rating": 3 }
{ "id": "3", "rating": 2 }

  Belge 2 ' nin iki kez getirildiğine dikkat edin.Notice that document 2 is fetched twice. Bunun nedeni, yeni belge 5 ' in derecelendirme için daha büyük olması, bu yüzden belge 2 ' den önce ve ilk sayfada yer bırakmadan önce sıralanır.This is because the new document 5 has a greater value for rating, so it sorts before document 2 and lands on the first page. Bu davranış beklenmeyen bir durum olsa da, bir arama altyapısının nasıl davrandığı normaldir.While this behavior might be unexpected, it's typical of how a search engine behaves.

Sonuçları sıralamaOrdering results

Tam metin arama sorguları için, sonuçlar, bir arama puanı tarafından otomatik olarak derecelendirilir, daha yüksek puanlar bir arama terimi üzerinde daha fazla veya daha fazla eşleşme elde eden belgeler.For full text search queries, results are automatically ranked by a search score, calculated based on term frequency and proximity in a document, with higher scores going to documents having more or stronger matches on a search term.

Arama puanları, aynı sonuç kümesindeki diğer belgelerle karşılaştırıldığında eşleşme gücünü yansıtan genel ilgi hissi elde ediyor.Search scores convey general sense of relevance, reflecting the strength of match as compared to other documents in the same result set. Puanlar bir sorgudan sonrakine her zaman tutarlı değildir. bu nedenle, sorgularla çalışırken arama belgelerinin nasıl sıralandığına ilişkin küçük tutarsızlıklar fark edebilirsiniz.Scores are not always consistent from one query to the next, so as you work with queries, you might notice small discrepancies in how search documents are ordered. Bunun neden olabileceği hakkında birkaç açıklamalar vardır.There are several explanations for why this might occur.

NedeniCause AçıklamaDescription
Veri VolaData volatility Belge eklerken, değiştirirken veya silerken Dizin içeriği farklılık gösterir.Index content varies as you add, modify, or delete documents. Dizin güncelleştirmeleri zaman içinde işlenirken, eşleşen belgelerin arama puanlarını etkileyen terim frekansları değişir.Term frequencies will change as index updates are processed over time, affecting the search scores of matching documents.
Birden çok çoğaltmaMultiple replicas Birden çok çoğaltma kullanan hizmetler için sorgular her bir çoğaltmaya paralel olarak verilir.For services using multiple replicas, queries are issued against each replica in parallel. Bir arama Puanını hesaplamak için kullanılan dizin istatistikleri çoğaltma temelinde hesaplanır, sonuçlar birleştirilir ve sorgu yanıtında sıralanır.The index statistics used to calculate a search score are calculated on a per-replica basis, with results merged and ordered in the query response. Çoğaltmalar genellikle birbirleriyle yansıtılıyordur, ancak durum bakımından küçük farklılıklar nedeniyle istatistikler farklılık gösterebilir.Replicas are mostly mirrors of each other, but statistics can differ due to small differences in state. Örneğin, bir çoğaltma, diğer çoğaltmalardan birleştirilmiş olan, istatistiklere katkıda bulunan belgeleri silmiş olabilir.For example, one replica might have deleted documents contributing to their statistics, which were merged out of other replicas. Genellikle, çoğaltma başına istatistikteki farklılıklar daha küçük dizinlerde daha belirgin olur.Typically, differences in per-replica statistics are more noticeable in smaller indexes.
Özdeş puanlarIdentical scores Birden çok belgede aynı puan varsa, bunlardan biri önce görünebilir.If multiple documents have the same score, any one of them might appear first.

Tutarlı sıralamaConsistent ordering

Sonuç sıralamasına göre esneklik verildiğinde, tutarlılık bir uygulama gereksinimidir, diğer seçenekleri incelemek isteyebilirsiniz.Given the flex in results ordering, you might want to explore other options if consistency is an application requirement. En kolay yaklaşım, derecelendirme veya tarih gibi bir alan değerine göre sıralıyor.The easiest approach is sorting by a field value, such as rating or date. Derecelendirme veya tarih gibi belirli bir alana göre sıralamak istediğiniz senaryolar için, sıralanabilirolarak dizini oluşturulmuş herhangi bir alana uygulanabilen bir $orderby ifadeyiaçıkça tanımlayabilirsiniz.For scenarios where you want to sort by a specific field, such as a rating or date, you can explicitly define an $orderby expression, which can be applied to any field that is indexed as Sortable.

Başka bir seçenek de özel bir Puanlama profilikullanıyor.Another option is using a custom scoring profile. Puanlama profilleri, belirli alanlarda bulunan eşleşmeleri artırma özelliği sayesinde, arama sonuçlarında öğelerin derecelendirmesi üzerinde daha fazla denetim sağlar.Scoring profiles give you more control over the ranking of items in search results, with the ability to boost matches found in specific fields. Ek Puanlama mantığı, her belge için arama puanları birbirinden farklı olduğundan çoğaltmalar arasındaki küçük farklılıkları geçersiz kılmaya yardımcı olabilir.The additional scoring logic can help override minor differences among replicas because the search scores for each document are farther apart. Bu yaklaşım için Derecelendirme algoritmasını öneririz.We recommend the ranking algorithm for this approach.

İsabet vurgulamaHit highlighting

İsabet vurgulama, bir sonuçla eşleşen terimlere uygulanan metin biçimlendirmesine (kalın veya sarı vurgular gibi) başvurur, bu da eşleştirmeyi daha kolay hale getirir.Hit highlighting refers to text formatting (such as bold or yellow highlights) applied to matching terms in a result, making it easy to spot the match. Sorgu isteğindeisabet vurgulama yönergeleri verilmiştir.Hit highlighting instructions are provided on the query request.

İsabet vurgulamasını etkinleştirmek için, highlight=[comma-delimited list of string fields] vurgulamayı hangi alanların vurgulakullanacağınızı belirtmek için ekleyin.To enable hit highlighting, add highlight=[comma-delimited list of string fields] to specify which fields will use highlighting. Vurgulama, bir açıklama alanı gibi daha uzun içerik alanları için yararlıdır, burada eşleşme hemen belirgin değildir.Highlighting is useful for longer content fields, such as a description field, where the match is not immediately obvious. Yalnızca arama için aranabilir olan alan tanımları, isabet vurgulama için geçerlidir.Only field definitions that are attributed as searchable qualify for hit highlighting.

Azure Bilişsel Arama, varsayılan olarak alan başına en fazla beş vurgu döndürür.By default, Azure Cognitive Search returns up to five highlights per field. Bu sayıyı alana ekleyerek bir kısa çizgi izleyen bir tamsayı ile ayarlayabilirsiniz.You can adjust this number by appending to the field a dash followed by an integer. Örneğin, highlight=Description-10 Açıklama alanında eşleşen içerik üzerinde en fazla 10 vurgu döndürür.For example, highlight=Description-10 returns up to 10 highlights on matching content in the Description field.

Biçimlendirme, tüm terim sorgularına uygulanır.Formatting is applied to whole term queries. Biçimlendirme türü etiketlere göre belirlenir ve highlightPreTag highlightPostTag kodunuz yanıtı işler (örneğin, kalın yazı tipi veya sarı arka plan uygulama).The type of formatting is determined by tags, highlightPreTag and highlightPostTag, and your code handles the response (for example, applying a bold font or a yellow background).

Aşağıdaki örnekte, açıklama alanı içindeki "Sandy", "kum", "kirekler", "plaj" terimleri vurgulama için etiketlendi.In the following example, the terms "sandy", "sand", "beaches", "beach" found within the Description field are tagged for highlighting. Benzer ve joker karakter arama gibi altyapıda sorgu genişletmeyi tetikleyen sorgular, isabet vurgulama için sınırlı desteğe sahiptir.Queries that trigger query expansion in the engine, such as fuzzy and wildcard search, have limited support for hit highlighting.

GET /indexes/hotels-sample-index/docs/search=sandy beaches&highlight=Description?api-version=2020-06-30 
POST /indexes/hotels-sample-index/docs/search?api-version=2020-06-30 
    {  
      "search": "sandy beaches",  
      "highlight": "Description"
    }

Yeni davranış (15 Temmuz 'dan itibaren)New behavior (starting July 15)

15 Temmuz 2020 ' den sonra oluşturulan hizmetler, farklı bir vurgulama deneyimi sağlar.Services created after July 15, 2020 will provide a different highlighting experience. Bu tarihten önce oluşturulan hizmetler, vurgulama davranışlarına göre değişmeyecektir.Services created before that date will not change in their highlighting behavior.

Yeni davranışla:With the new behavior:

  • Yalnızca tam tümcecik sorgusuyla eşleşen ifadeler döndürülür.Only phrases that match the full phrase query will be returned. "Super una" sorgusu şöyle sonuç verecektir:The query "super bowl" will return highlights like this:

    '<em>super bowl</em> is super awesome with a bowl of chips'
    

    Yongalar teriminin, tam tümcecikle eşleşmediğinden hiçbir vurgulamaya sahip olmadığını unutmayın.Note that the term bowl of chips does not have any highlighting because it does not match the full phrase.

İsabet vurgulama uygulayan istemci kodu yazarken, bu değişikliği unutmayın.When you are writing client code that implements hit highlighting, be aware of this change. Tamamen yeni bir arama hizmeti oluşturmadığınız takdirde bunu etkilemeyecektir.Note that this will not impact you unless you create a completely new search service.

Sonraki adımlarNext steps

İstemcinizi hızlı bir şekilde bir arama sayfası oluşturmak için aşağıdaki seçenekleri göz önünde bulundurun:To quickly generate a search page for your client, consider these options:

  • Uygulama Oluşturucu, portalda bir arama çubuğu, çok yönlü gezinme ve görüntü içeren sonuç alanı IÇEREN bir HTML sayfası oluşturur.Application Generator, in the portal, creates an HTML page with a search bar, faceted navigation, and results area that includes images.
  • C# ' de ilk uygulamanızı oluşturma işlevsel bir istemci oluşturan bir öğreticidir.Create your first app in C# is a tutorial that builds a functional client. Örnek kod, sayfalandırılmış sorguları, isabet vurgulamasını ve sıralamayı gösterir.Sample code demonstrates paginated queries, hit highlighting, and sorting.

Birçok kod örneği, burada bulabileceğiniz bir Web ön uç arabirimi içerir: New York City işleri tanıtım uygulaması, canlı tanıtım sitesiyle JavaScript örnek koduve bilivesearchön uç.Several code samples include a web front-end interface, which you can find here: New York City Jobs demo app, JavaScript sample code with a live demo site, and CognitiveSearchFrontEnd.