@azure/search-documents 12.0.0-beta.4 → 12.1.0-beta.1

package/README.md

@@ -1,23 +1,33 @@
-# Azure Cognitive Search client library for JavaScript
+# Azure AI Search client library for JavaScript
 
-[Azure Cognitive Search](https://docs.microsoft.com/azure/search/) is a search-as-a-service cloud solution that gives developers APIs and tools for adding a rich search experience over private, heterogeneous content in web, mobile, and enterprise applications.
+[Azure AI Search](https://docs.microsoft.com/azure/search/) (formerly known as "Azure Cognitive Search") is an AI-powered information retrieval platform that helps developers build rich search experiences and generative AI apps that combine large language models with enterprise data.
 
-The Azure Cognitive Search service is well suited for the following application scenarios:
+The Azure AI Search service is well suited for the following application scenarios:
 
-- Consolidate varied content types into a single searchable index. To populate an index, you can push JSON documents that contain your content, or if your data is already in Azure, create an indexer to pull in data automatically.
-- Attach skillsets to an indexer to create searchable content from images and large text documents. A skillset leverages AI from Cognitive Services for built-in OCR, entity recognition, key phrase extraction, language detection, text translation, and sentiment analysis. You can also add custom skills to integrate external processing of your content during data ingestion.
-- In a search client application, implement query logic and user experiences similar to commercial web search engines.
+* Consolidate varied content types into a single searchable index.
+  To populate an index, you can push JSON documents that contain your content,
+  or if your data is already in Azure, create an indexer to pull in data
+  automatically.
+* Attach skillsets to an indexer to create searchable content from images
+  and unstructured documents. A skillset leverages APIs from Azure AI Services
+  for built-in OCR, entity recognition, key phrase extraction, language
+  detection, text translation, and sentiment analysis. You can also add
+  custom skills to integrate external processing of your content during
+  data ingestion.
+* In a search client application, implement query logic and user experiences
+  similar to commercial web search engines and chat-style apps.
 
 Use the @azure/search-documents client library to:
 
-- Submit queries for simple and advanced query forms that include fuzzy search, wildcard search, regular expressions.
-- Implement filtered queries for faceted navigation, geospatial search, or to narrow results based on filter criteria.
-- Create and manage search indexes.
-- Upload and update documents in the search index.
-- Create and manage indexers that pull data from Azure into an index.
-- Create and manage skillsets that add AI enrichment to data ingestion.
-- Create and manage analyzers for advanced text analysis or multi-lingual content.
-- Optimize results through scoring profiles to factor in business logic or freshness.
+* Submit queries using vector, keyword, and hybrid query forms.
+* Implement filtered queries for metadata, geospatial search, faceted navigation, 
+  or to narrow results based on filter criteria.
+* Create and manage search indexes.
+* Upload and update documents in the search index.
+* Create and manage indexers that pull data from Azure into an index.
+* Create and manage skillsets that add AI enrichment to data ingestion.
+* Create and manage analyzers for advanced text analysis or multi-lingual content.
+* Optimize results through semantic ranking and scoring profiles to factor in business logic or freshness.
 
 Key links:
 
@@ -39,7 +49,7 @@ npm install @azure/search-documents
 ### Currently supported environments
 
 - [LTS versions of Node.js](https://github.com/nodejs/release#release-schedule)
-- Latest versions of Safari, Chrome, Edge, and Firefox.
+- Latest versions of Safari, Chrome, Microsoft Edge, and Firefox.
 
 See our [support policy](https://github.com/Azure/azure-sdk-for-js/blob/main/SUPPORT.md) for more details.
 
@@ -58,16 +68,20 @@ See [choosing a pricing tier](https://docs.microsoft.com/azure/search/search-sku
 
 ### Authenticate the client
 
-All requests to a search service need an API key that was generated specifically for your service. [The API key is the sole mechanism for authenticating access to your search service endpoint.](https://docs.microsoft.com/azure/search/search-security-api-keys)
+To interact with the search service, you'll need to create an instance of the appropriate client class: `SearchClient` for searching indexed documents, `SearchIndexClient` for managing indexes, or `SearchIndexerClient` for crawling data sources and loading search documents into an index. To instantiate a client object, you'll need an **endpoint** and **Azure roles** or an **API key**. You can refer to the documentation for more information on [supported authenticating approaches](https://learn.microsoft.com/azure/search/search-security-overview#authentication) with the search service.
 
-You can obtain your api-key from the [Azure portal](https://portal.azure.com/) or via the Azure CLI:
+#### Get an API Key
 
-```PowerShell
+An API key can be an easier approach to start with because it doesn't require pre-existing role assignments.
+
+You can get the **endpoint** and an **API key** from the search service in the [Azure portal](https://portal.azure.com/). Please refer the [documentation](https://docs.microsoft.com/azure/search/search-security-api-keys) for instructions on how to get an API key.
+
+Alternatively, you can use the following [Azure CLI](https://learn.microsoft.com/cli/azure/) command to retrieve the API key from the search service:
+
+```Powershell
 az search admin-key show --resource-group <your-resource-group-name> --service-name <your-resource-name>
 ```
 
-Alternatively, you can get the endpoint and Admin Key from the resource information in the [Azure Portal][azure_portal].
-
 There are two types of keys used to access your search service: **admin** _(read-write)_ and **query** _(read-only)_ keys. Restricting access and operations in client apps is essential to safeguarding the search assets on your service. Always use a query key rather than an admin key for any query originating from a client app.
 
 _Note: The example Azure CLI snippet above retrieves an admin key so it's easier to get started exploring APIs, but it should be managed carefully._
@@ -134,17 +148,24 @@ const indexerClient = new SearchIndexerClient("<endpoint>", new AzureKeyCredenti
 
 ## Key concepts
 
-An Azure Cognitive Search service contains one or more indexes that provide persistent storage of searchable data in the form of JSON documents. _(If you're brand new to search, you can make a very rough analogy between indexes and database tables.)_ The @azure/search-documents client library
+An Azure AI Search service contains one or more indexes that provide persistent storage of searchable data in the form of JSON documents. _(If you're brand new to search, you can make a very rough analogy between indexes and database tables.)_ The @azure/search-documents client library
 exposes operations on these resources through three main client types.
 
 - `SearchClient` helps with:
-  - [Searching](https://docs.microsoft.com/azure/search/search-lucene-query-architecture) your indexed documents using [rich queries](https://docs.microsoft.com/azure/search/search-query-overview) and [powerful data shaping](https://docs.microsoft.com/azure/search/search-filters)
+  - [Searching](https://docs.microsoft.com/azure/search/search-lucene-query-architecture)
+    your indexed documents using [vector queries](https://learn.microsoft.com/azure/search/vector-search-how-to-query),
+    [keyword queries](https://learn.microsoft.com/azure/search/search-query-create)
+    and [hybrid queries](https://learn.microsoft.com/azure/search/hybrid-search-how-to-query)
+  - [Vector query filters](https://learn.microsoft.com/azure/search/vector-search-filters) and [Text query filters](https://learn.microsoft.com/azure/search/search-filters)
+  - [Semantic ranking](https://learn.microsoft.com/azure/search/semantic-how-to-query-request) and [scoring profiles](https://learn.microsoft.com/azure/search/index-add-scoring-profiles) for boosting relevance
   - [Autocompleting](https://docs.microsoft.com/rest/api/searchservice/autocomplete) partially typed search terms based on documents in the index
   - [Suggesting](https://docs.microsoft.com/rest/api/searchservice/suggestions) the most likely matching text in documents as a user types
   - [Adding, Updating or Deleting Documents](https://docs.microsoft.com/rest/api/searchservice/addupdate-or-delete-documents) documents from an index
+
 - `SearchIndexClient` allows you to:
   - [Create, delete, update, or configure a search index](https://docs.microsoft.com/rest/api/searchservice/index-operations)
   - [Declare custom synonym maps to expand or rewrite queries](https://docs.microsoft.com/rest/api/searchservice/synonym-map-operations)
+
 - `SearchIndexerClient` allows you to:
   - [Start indexers to automatically crawl data sources](https://docs.microsoft.com/rest/api/searchservice/indexer-operations)
   - [Define AI powered Skillsets to transform and enrich your data](https://docs.microsoft.com/rest/api/searchservice/skillset-operations)
@@ -328,14 +349,14 @@ interface Hotel {
   hotelId?: string;
   hotelName?: string | null;
   description?: string | null;
-  descriptionVector?: Array<number> | null;
+  descriptionVector?: Array<number>;
   parkingIncluded?: boolean | null;
   lastRenovationDate?: Date | null;
   rating?: number | null;
   rooms?: Array<{
     beds?: number | null;
     description?: string | null;
-  } | null>;
+  }>;
 }
 
 const client = new SearchClient<Hotel>(
@@ -354,7 +375,7 @@ async function main() {
   // These are other ways to declare the correct type for `select`.
   const select = ["hotelId", "hotelName", "rooms/beds"] as const;
   // This declaration lets you opt out of narrowing the TypeScript type of your documents,
-  // though the Cognitive Search service will still only return these fields.
+  // though the AI Search service will still only return these fields.
   const selectWide: SelectFields<Hotel>[] = ["hotelId", "hotelName", "rooms/beds"];
   // This is an invalid declaration. Passing this to `select` will result in a compiler error
   // unless you opt out of including the model in the client constructor.
@@ -385,7 +406,7 @@ async function main() {
   const searchResults = await client.search("WiFi", {
     filter: odata`Rooms/any(room: room/BaseRate lt ${baseRateMax}) and Rating ge ${ratingMin}`,
     orderBy: ["Rating desc"],
-    select: ["hotelId", "hotelName", "rating"],
+    select: ["hotelId", "hotelName", "Rating"],
   });
   for await (const result of searchResults.results) {
     // Each result will have "HotelId", "HotelName", and "Rating"
@@ -399,7 +420,7 @@ main();
 
 #### Querying with vectors
 
-Text embeddings can be queried using the `vector` search parameter.
+Text embeddings can be queried using the `vector` search parameter. See [Query vectors](https://learn.microsoft.com/azure/search/vector-search-how-to-query) and [Filter vector queries](https://learn.microsoft.com/azure/search/vector-search-filters) for more information.
 
 ```js
 const { SearchClient, AzureKeyCredential, odata } = require("@azure/search-documents");
@@ -462,7 +483,7 @@ When retrieving results, a `facets` property will be available that will indicat
 
 ### Logging
 
-Enabling logging may help uncover useful information about failures. In order to see a log of HTTP requests and responses, set the `AZURE_LOG_LEVEL` environment variable to `info`. Alternatively, logging can be enabled at runtime by calling `setLogLevel` in the `@azure/logger`:
+Enabling logging can help uncover useful information about failures. In order to see a log of HTTP requests and responses, set the `AZURE_LOG_LEVEL` environment variable to `info`. Alternatively, logging can be enabled at runtime by calling `setLogLevel` in the `@azure/logger`:
 
 ```javascript
 import { setLogLevel } from "@azure/logger";
@@ -475,8 +496,7 @@ For more detailed instructions on how to enable logs, you can look at the [@azur
 ## Next steps
 
 - [Go further with search-documents and our samples](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/search/search-documents/samples)
-- [Watch a demo or deep dive video](https://azure.microsoft.com/resources/videos/index/?services=search)
-- [Read more about the Azure Cognitive Search service](https://docs.microsoft.com/azure/search/search-what-is-azure-search)
+- [Read more about the Azure AI Search service](https://docs.microsoft.com/azure/search/search-what-is-azure-search)
 
 ## Contributing
 
@@ -484,11 +504,11 @@ If you'd like to contribute to this library, please read the [contributing guide
 
 This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit [cla.microsoft.com][cla].
 
-This project has adopted the [Microsoft Open Source Code of Conduct][coc].For more information see the [Code of Conduct FAQ][coc_faq] or contact [opencode@microsoft.com][coc_contact] with any additional questions or comments.
+This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For more information see the [Code of Conduct FAQ][coc_faq] or contact [opencode@microsoft.com][coc_contact] with any additional questions or comments.
 
 ## Related projects
 
-- [Microsoft Azure SDK for Javascript](https://github.com/Azure/azure-sdk-for-js)
+- [Microsoft Azure SDK for JavaScript](https://github.com/Azure/azure-sdk-for-js)
 
 ![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-js%2Fsdk%2Fsearch%2Fsearch%2FREADME.png)