Module azure.ai.search.index

ballerinax/azure.ai.search.index Ballerina library

1.0.2

Overview

Azure AI Search is a cloud search service with built-in AI capabilities. It provides the Azure AI Search REST API to access powerful search and indexing functionality, enabling the creation of rich search experiences.

The Azure AI Search Index connector offers functionality to connect and interact with the Azure AI Search Index Management REST API, allowing seamless interaction with search indexes, documents, and search operations.

Key Features

Efficient management of search indexes and documents
Support for Azure AI Search Index Management REST API
Intelligent search capabilities with built-in AI
Seamless integration with Azure's cloud search infrastructure

Setup guide

To use the Azure AI Search Index Connector, you must have access to Azure AI Search through an Azure account and a search service resource. If you do not have an Azure account, you can sign up for one at the Azure website.

Create an Azure AI Search Service

Open the Azure Portal.
Navigate to Create a resource -> AI + Machine Learning -> Search service.
Fill in the required details:
- Resource group
- Service name
- Location
- Pricing tier
Review and create the search service.
Once the service is deployed, navigate to the service and obtain the service URL and Admin API keys from the "Keys" section.
Store the service URL and API key securely to use in your application.

Quickstart

To use the Azure AI Search Index connector in your Ballerina application, update the .bal file as follows:

Step 1: Import the module

Import the ballerinax/azure.ai.search.index module.


import ballerinax/azure.ai.search.index;

Step 2: Create a new connector instance

Create an azure.ai.search.index:Client with the obtained service URL and API Key and initialize the connector.


configurable string serviceUrl = ?;
configurable string apiKey = ?;
configurable string indexName = "my-test-index";

final index:Client azureSearchIndexClient = check new (string `${serviceUrl}/indexes/${indexName}`);
index:DocumentsSearchGetHeaders headers = {"api-key": apiKey};

Step 3: Invoke the connector operation

Now, you can utilize available connector operations.

Search for documents in an index


public function main() returns error? {

    // Search for documents
    index:SearchDocumentsResult searchDocumentsResult = check azureSearchIndexClient->documentsSearchGet(headers,
        api\-version = "2025-09-01",
        search = searchTerm,
        \$count = true,
        \$select = ["content"]
    );
    
    // Process search results
    index:SearchResult[] documents = searchDocumentsResult.value;
    io:println(string`Found ${documents.length()} documents for "${searchTerm}":`);
    foreach index:SearchResult doc in documents {
        io:println(doc.toJsonString());
    }
}

Step 4: Run the Ballerina application


bal run

Examples

The Azure AI Search Index connector provides practical examples illustrating usage in various scenarios. Explore these examples, covering the following use cases:

Document search - Search for documents in an Azure AI Search index with various query parameters and filters.

Clients

azure.ai.search.index: Client

Isolated

Client that can be used to query an index and upload, merge, or delete documents.

Constructor

Gets invoked to initialize the connector.

init (string serviceUrl, ConnectionConfig config)

serviceUrl string - URL of the target service

config ConnectionConfig {} - The configurations to be used when initializing the connector

documentsCount

Isolated FunctionRemote Function

function documentsCount(DocumentsCountHeaders headers, *DocumentsCountQueries queries) returns int|error

Queries the number of documents in the index.

Parameters

headers DocumentsCountHeaders (default {}) - Headers to be sent with the request

queries *DocumentsCountQueries - Queries to be sent with the request

documentsSearchGet

Isolated FunctionRemote Function

function documentsSearchGet(DocumentsSearchGetHeaders headers, *DocumentsSearchGetQueries queries) returns SearchDocumentsResult|error

Searches for documents in the index.

Parameters

headers DocumentsSearchGetHeaders (default {}) - Headers to be sent with the request

queries *DocumentsSearchGetQueries - Queries to be sent with the request

Return Type

SearchDocumentsResult|error - Response containing documents that match the search criteria.

documentsSearchPost

Isolated FunctionRemote Function

function documentsSearchPost(docs_search_post_search_body payload, DocumentsSearchPostHeaders headers, *DocumentsSearchPostQueries queries) returns SearchDocumentsResult|error

Searches for documents in the index.

Parameters

payload docs_search_post_search_body - The definition of the Search request.

headers DocumentsSearchPostHeaders (default {}) - Headers to be sent with the request

queries *DocumentsSearchPostQueries - Queries to be sent with the request

Return Type

SearchDocumentsResult|error - Response containing documents that match the search criteria.

documentsGet

Isolated FunctionRemote Function

function documentsGet(string 'key, DocumentsGetHeaders headers, *DocumentsGetQueries queries) returns LookupDocument|error

Retrieves a document from the index.

Parameters

'key string - The key of the document to retrieve.

headers DocumentsGetHeaders (default {}) - Headers to be sent with the request

queries *DocumentsGetQueries - Queries to be sent with the request

Return Type

LookupDocument|error - Response containing the requested document.

documentsSuggestGet

Isolated FunctionRemote Function

function documentsSuggestGet(DocumentsSuggestGetHeaders headers, *DocumentsSuggestGetQueries queries) returns SuggestDocumentsResult|error

Suggests documents in the index that match the given partial query text.

Parameters

headers DocumentsSuggestGetHeaders (default {}) - Headers to be sent with the request

queries *DocumentsSuggestGetQueries - Queries to be sent with the request

Return Type

SuggestDocumentsResult|error - Response containing suggested documents that match the partial input.

documentsSuggestPost

Isolated FunctionRemote Function

function documentsSuggestPost(SuggestRequest payload, DocumentsSuggestPostHeaders headers, *DocumentsSuggestPostQueries queries) returns SuggestDocumentsResult|error

Suggests documents in the index that match the given partial query text.

Parameters

payload SuggestRequest - The Suggest request.

headers DocumentsSuggestPostHeaders (default {}) - Headers to be sent with the request

queries *DocumentsSuggestPostQueries - Queries to be sent with the request

Return Type

SuggestDocumentsResult|error - Response containing suggested documents that match the partial input.

documentsIndex

Isolated FunctionRemote Function

function documentsIndex(IndexBatch payload, DocumentsIndexHeaders headers, *DocumentsIndexQueries queries) returns IndexDocumentsResult|error

Sends a batch of document write actions to the index.

Parameters

payload IndexBatch - The batch of index actions.

headers DocumentsIndexHeaders (default {}) - Headers to be sent with the request

queries *DocumentsIndexQueries - Queries to be sent with the request

Return Type

IndexDocumentsResult|error - Response containing the status of operations for all actions in the batch.

documentsAutocompleteGet

Isolated FunctionRemote Function

function documentsAutocompleteGet(DocumentsAutocompleteGetHeaders headers, *DocumentsAutocompleteGetQueries queries) returns AutocompleteResult|error

Autocompletes incomplete query terms based on input text and matching terms in the index.

Parameters

headers DocumentsAutocompleteGetHeaders (default {}) - Headers to be sent with the request

queries *DocumentsAutocompleteGetQueries - Queries to be sent with the request

Return Type

AutocompleteResult|error - Response containing suggested query terms that complete the partial input.

documentsAutocompletePost

Isolated FunctionRemote Function

function documentsAutocompletePost(AutocompleteRequest payload, DocumentsAutocompletePostHeaders headers, *DocumentsAutocompletePostQueries queries) returns AutocompleteResult|error

Autocompletes incomplete query terms based on input text and matching terms in the index.

Parameters

payload AutocompleteRequest - The definition of the Autocomplete request.

headers DocumentsAutocompletePostHeaders (default {}) - Headers to be sent with the request

queries *DocumentsAutocompletePostQueries - Queries to be sent with the request

Return Type

AutocompleteResult|error - Response containing suggested query terms that complete the partial input.

Records

azure.ai.search.index: AnswerResult

An answer is a text passage extracted from the contents of the most relevant documents that matched the query. Answers are extracted from the top search results. Answer candidates are scored and the top answers are selected.

Fields

score? decimal - The score value represents how relevant the answer is to the query relative to other answers returned for the query.

'key? string - The key of the document the answer was extracted from.

text? string - The text passage extracted from the document contents as the answer.

highlights? string? - Same text passage as in the Text property with highlighted text phrases most relevant to the query.

azure.ai.search.index: AutocompleteItem

The result of Autocomplete requests.

Fields

text string - The completed term.

queryPlusText string - The query along with the completed term.

azure.ai.search.index: AutocompleteRequest

Parameters for fuzzy matching, and other autocomplete query behaviors.

Fields

search string - The search text on which to base autocomplete results.

autocompleteMode? AutocompleteMode - Specifies the mode for Autocomplete. The default is 'oneTerm'. Use 'twoTerms' to get shingles and 'oneTermWithContext' to use the current context in producing autocomplete terms.

filter? string - An OData expression that filters the documents used to produce completed terms for the Autocomplete result.

fuzzy? boolean - A value indicating whether to use fuzzy matching for the autocomplete query. Default is false. When set to true, the query will autocomplete terms even if there's a substituted or missing character in the search text. While this provides a better experience in some scenarios, it comes at a performance cost as fuzzy autocomplete queries are slower and consume more resources.

highlightPostTag? string - A string tag that is appended to hit highlights. Must be set with highlightPreTag. If omitted, hit highlighting is disabled.

highlightPreTag? string - A string tag that is prepended to hit highlights. Must be set with highlightPostTag. If omitted, hit highlighting is disabled.

minimumCoverage? decimal - A number between 0 and 100 indicating the percentage of the index that must be covered by an autocomplete query in order for the query to be reported as a success. This parameter can be useful for ensuring search availability even for services with only one replica. The default is 80.

searchFields? string - The comma-separated list of field names to consider when querying for auto-completed terms. Target fields must be included in the specified suggester.

suggesterName string - The name of the suggester as specified in the suggesters collection that's part of the index definition.

top? Signed32 - The number of auto-completed terms to retrieve. This must be a value between 1 and 100. The default is 5.

azure.ai.search.index: AutocompleteResult

The result of Autocomplete query.

Fields

\@search\.coverage? decimal - A value indicating the percentage of the index that was considered by the autocomplete request, or null if minimumCoverage was not specified in the request.

value AutocompleteItem[] - The list of returned Autocompleted items.

azure.ai.search.index: CaptionResult

Captions are the most representative passages from the document relatively to the search query. They are often used as document summary. Captions are only returned for queries of type semantic.

Fields

text? string - A representative text passage extracted from the document most relevant to the search query.

highlights? string? - Same text passage as in the Text property with highlighted phrases most relevant to the query.

azure.ai.search.index: ConnectionConfig

Closed record

Provides a set of configurations for controlling the behaviours when communicating with a remote HTTP endpoint.

Fields

httpVersion HttpVersion(default http:HTTP_2_0) - The HTTP version understood by the client

http1Settings ClientHttp1Settings(default {}) - Configurations related to HTTP/1.x protocol

http2Settings ClientHttp2Settings(default {}) - Configurations related to HTTP/2 protocol

timeout decimal(default 30) - The maximum time to wait (in seconds) for a response before closing the connection

forwarded string(default "disable") - The choice of setting forwarded/x-forwarded header

followRedirects? FollowRedirects - Configurations associated with Redirection

poolConfig? PoolConfiguration - Configurations associated with request pooling

cache CacheConfig(default {}) - HTTP caching related configurations

compression Compression(default http:COMPRESSION_AUTO) - Specifies the way of handling compression (accept-encoding) header

circuitBreaker? CircuitBreakerConfig - Configurations associated with the behaviour of the Circuit Breaker

retryConfig? RetryConfig - Configurations associated with retrying

cookieConfig? CookieConfig - Configurations associated with cookies

responseLimits ResponseLimitConfigs(default {}) - Configurations associated with inbound response size limits

secureSocket? ClientSecureSocket - SSL/TLS-related options

proxy? ProxyConfig - Proxy server related options

socketConfig ClientSocketConfig(default {}) - Provides settings related to client socket configuration

validation boolean(default true) - Enables the inbound payload validation functionality which provided by the constraint package. Enabled by default

laxDataBinding boolean(default true) - Enables relaxed data binding on the client side. When enabled, nil values are treated as optional, and absent fields are handled as nilable types. Enabled by default.

azure.ai.search.index: DocumentDebugInfo

Contains debugging information that can be used to further explore your search results.

Fields

vectors? VectorsDebugInfo -

azure.ai.search.index: DocumentsAutocompleteGetHeaders

Represents the Headers record for the operation: documentsAutocompleteGet

Fields

x\-ms\-client\-request\-id? string - The tracking ID sent with the request to help with debugging.

azure.ai.search.index: DocumentsAutocompleteGetQueries

Represents the Queries record for the operation: documentsAutocompleteGet

Fields

api\-version string - Client Api Version.

search string - The incomplete term which should be auto-completed.

minimumCoverage? decimal - A number between 0 and 100 indicating the percentage of the index that must be covered by an autocomplete query in order for the query to be reported as a success. This parameter can be useful for ensuring search availability even for services with only one replica. The default is 80.

autocompleteMode? "oneTerm"|"twoTerms"|"oneTermWithContext" - Specifies the mode for Autocomplete. The default is 'oneTerm'. Use 'twoTerms' to get shingles and 'oneTermWithContext' to use the current context while producing auto-completed terms.

\$top? Signed32 - The number of auto-completed terms to retrieve. This must be a value between 1 and 100. The default is 5.

\$filter? string - An OData expression that filters the documents used to produce completed terms for the Autocomplete result.

suggesterName string - The name of the suggester as specified in the suggesters collection that's part of the index definition.

highlightPostTag? string - A string tag that is appended to hit highlights. Must be set with highlightPreTag. If omitted, hit highlighting is disabled.

searchFields? string[] - The list of field names to consider when querying for auto-completed terms. Target fields must be included in the specified suggester.

highlightPreTag? string - A string tag that is prepended to hit highlights. Must be set with highlightPostTag. If omitted, hit highlighting is disabled.

fuzzy? boolean - A value indicating whether to use fuzzy matching for the autocomplete query. Default is false. When set to true, the query will find terms even if there's a substituted or missing character in the search text. While this provides a better experience in some scenarios, it comes at a performance cost as fuzzy autocomplete queries are slower and consume more resources.

azure.ai.search.index: DocumentsAutocompletePostHeaders

Represents the Headers record for the operation: documentsAutocompletePost

Fields

x\-ms\-client\-request\-id? string - The tracking ID sent with the request to help with debugging.

azure.ai.search.index: DocumentsAutocompletePostQueries

Represents the Queries record for the operation: documentsAutocompletePost

Fields

api\-version string - Client Api Version.

azure.ai.search.index: DocumentsCountHeaders

Represents the Headers record for the operation: documentsCount

Fields

x\-ms\-client\-request\-id? string - The tracking ID sent with the request to help with debugging.

azure.ai.search.index: DocumentsCountQueries

Represents the Queries record for the operation: documentsCount

Fields

api\-version string - Client Api Version.

azure.ai.search.index: DocumentsGetHeaders

Represents the Headers record for the operation: documentsGet

Fields

x\-ms\-client\-request\-id? string - The tracking ID sent with the request to help with debugging.

azure.ai.search.index: DocumentsGetQueries

Represents the Queries record for the operation: documentsGet

Fields

api\-version string - Client Api Version.

\$select? string[] - List of field names to retrieve for the document; Any field not retrieved will be missing from the returned document.

azure.ai.search.index: DocumentsIndexHeaders

Represents the Headers record for the operation: documentsIndex

Fields

x\-ms\-client\-request\-id? string - The tracking ID sent with the request to help with debugging.

azure.ai.search.index: DocumentsIndexQueries

Represents the Queries record for the operation: documentsIndex

Fields

api\-version string - Client Api Version.

azure.ai.search.index: DocumentsSearchGetHeaders

Represents the Headers record for the operation: documentsSearchGet

Fields

x\-ms\-client\-request\-id? string - The tracking ID sent with the request to help with debugging.

azure.ai.search.index: DocumentsSearchGetQueries

Represents the Queries record for the operation: documentsSearchGet

Fields

semanticMaxWaitInMilliseconds? Signed32 - Allows the user to set an upper bound on the amount of time it takes for semantic enrichment to finish processing before the request fails.

api\-version string - Client Api Version.

semanticQuery? string - Allows setting a separate search query that will be solely used for semantic reranking, semantic captions and semantic answers. Is useful for scenarios where there is a need to use different queries between the base retrieval and ranking phase, and the L2 semantic phase.

scoringProfile? string - The name of a scoring profile to evaluate match scores for matching documents in order to sort the results.

searchMode? "any"|"all" - A value that specifies whether any or all of the search terms must be matched in order to count the document as a match.

answers? "none"|"extractive" - This parameter is only valid if the query type is semantic. If set, the query returns answers extracted from key passages in the highest ranked documents. The number of answers returned can be configured by appending the pipe character | followed by the count-<number of answers> option after the answers parameter value, such as extractive|count-3. Default count is 1. The confidence threshold can be configured by appending the pipe character | followed by the threshold-<confidence threshold> option after the answers parameter value, such as extractive|threshold-0.9. Default threshold is 0.7.

captions? "none"|"extractive" - This parameter is only valid if the query type is semantic. If set, the query returns captions extracted from key passages in the highest ranked documents. When Captions is set to extractive, highlighting is enabled by default, and can be configured by appending the pipe character | followed by the highlight-<true/false> option, such as extractive|highlight-true. Defaults to None.

highlight? string[] - The list of field names to use for hit highlights. Only searchable fields can be used for hit highlighting.

search? string - A full-text search query expression; Use "*" or omit this parameter to match all documents.

minimumCoverage? decimal - A number between 0 and 100 indicating the percentage of the index that must be covered by a search query in order for the query to be reported as a success. This parameter can be useful for ensuring search availability even for services with only one replica. The default is 100.

\$skip? Signed32 - The number of search results to skip. This value cannot be greater than 100,000. If you need to scan documents in sequence, but cannot use $skip due to this limitation, consider using $orderby on a totally-ordered key and $filter with a range query instead.

scoringParameter? string[] - The list of parameter values to be used in scoring functions (for example, referencePointParameter) using the format name-values. For example, if the scoring profile defines a function with a parameter called 'mylocation' the parameter string would be "mylocation--122.2,44.8" (without the quotes).

searchFields? string[] - The list of field names to which to scope the full-text search. When using fielded search (fieldName:searchExpression) in a full Lucene query, the field names of each fielded search expression take precedence over any field names listed in this parameter.

semanticConfiguration? string - The name of the semantic configuration that lists which fields should be used for semantic ranking, captions, highlights, and answers

\$top? Signed32 - The number of search results to retrieve. This can be used in conjunction with $skip to implement client-side paging of search results. If results are truncated due to server-side paging, the response will include a continuation token that can be used to issue another Search request for the next page of results.

debug? "disabled"|"vector" - Enables a debugging tool that can be used to further explore your search results.

sessionId? string - A value to be used to create a sticky session, which can help to get more consistent results. As long as the same sessionId is used, a best-effort attempt will be made to target the same replica set. Be wary that reusing the same sessionID values repeatedly can interfere with the load balancing of the requests across replicas and adversely affect the performance of the search service. The value used as sessionId cannot start with a '_' character.

highlightPreTag? string - A string tag that is prepended to hit highlights. Must be set with highlightPostTag. Default is <em>.

semanticErrorHandling? "partial"|"fail" - Allows the user to choose whether a semantic call should fail completely, or to return partial results (default).

queryType? "simple"|"full"|"semantic" - A value that specifies the syntax of the search query. The default is 'simple'. Use 'full' if your query uses the Lucene query syntax.

scoringStatistics? "local"|"global" - A value that specifies whether we want to calculate scoring statistics (such as document frequency) globally for more consistent scoring, or locally, for lower latency.

\$filter? string - The OData $filter expression to apply to the search query.

\$orderby? string[] - The list of OData $orderby expressions by which to sort the results. Each expression can be either a field name or a call to either the geo.distance() or the search.score() functions. Each expression can be followed by asc to indicate ascending, and desc to indicate descending. The default is ascending order. Ties will be broken by the match scores of documents. If no OrderBy is specified, the default sort order is descending by document match score. There can be at most 32 $orderby clauses.

highlightPostTag? string - A string tag that is appended to hit highlights. Must be set with highlightPreTag. Default is </em>.

\$count? boolean - A value that specifies whether to fetch the total count of results. Default is false. Setting this value to true may have a performance impact. Note that the count returned is an approximation.

\$select? string[] - The list of fields to retrieve. If unspecified, all fields marked as retrievable in the schema are included.

azure.ai.search.index: DocumentsSearchPostHeaders

Represents the Headers record for the operation: documentsSearchPost

Fields

x\-ms\-client\-request\-id? string - The tracking ID sent with the request to help with debugging.

azure.ai.search.index: DocumentsSearchPostQueries

Represents the Queries record for the operation: documentsSearchPost

Fields

api\-version string - Client Api Version.

azure.ai.search.index: DocumentsSuggestGetHeaders

Represents the Headers record for the operation: documentsSuggestGet

Fields

x\-ms\-client\-request\-id? string - The tracking ID sent with the request to help with debugging.

azure.ai.search.index: DocumentsSuggestGetQueries

Represents the Queries record for the operation: documentsSuggestGet

Fields

api\-version string - Client Api Version.

search string - The search text to use to suggest documents. Must be at least 1 character, and no more than 100 characters.

minimumCoverage? decimal - A number between 0 and 100 indicating the percentage of the index that must be covered by a suggestions query in order for the query to be reported as a success. This parameter can be useful for ensuring search availability even for services with only one replica. The default is 80.

\$top? Signed32 - The number of suggestions to retrieve. The value must be a number between 1 and 100. The default is 5.

\$filter? string - An OData expression that filters the documents considered for suggestions.

\$orderby? string[] - The list of OData $orderby expressions by which to sort the results. Each expression can be either a field name or a call to either the geo.distance() or the search.score() functions. Each expression can be followed by asc to indicate ascending, or desc to indicate descending. The default is ascending order. Ties will be broken by the match scores of documents. If no $orderby is specified, the default sort order is descending by document match score. There can be at most 32 $orderby clauses.

suggesterName string - The name of the suggester as specified in the suggesters collection that's part of the index definition.

highlightPostTag? string - A string tag that is appended to hit highlights. Must be set with highlightPreTag. If omitted, hit highlighting of suggestions is disabled.

searchFields? string[] - The list of field names to search for the specified search text. Target fields must be included in the specified suggester.

highlightPreTag? string - A string tag that is prepended to hit highlights. Must be set with highlightPostTag. If omitted, hit highlighting of suggestions is disabled.

fuzzy? boolean - A value indicating whether to use fuzzy matching for the suggestions query. Default is false. When set to true, the query will find terms even if there's a substituted or missing character in the search text. While this provides a better experience in some scenarios, it comes at a performance cost as fuzzy suggestions queries are slower and consume more resources.

\$select? string[] - The list of fields to retrieve. If unspecified, only the key field will be included in the results.

azure.ai.search.index: DocumentsSuggestPostHeaders

Represents the Headers record for the operation: documentsSuggestPost

Fields

x\-ms\-client\-request\-id? string - The tracking ID sent with the request to help with debugging.

azure.ai.search.index: DocumentsSuggestPostQueries

Represents the Queries record for the operation: documentsSuggestPost

Fields

api\-version string - Client Api Version.

azure.ai.search.index: FacetResult

A single bucket of a facet query result. Reports the number of documents with a field value falling within a particular range or having a particular value or interval.

Fields

count? int - The approximate count of documents falling within the bucket described by this facet.

azure.ai.search.index: IndexAction

Represents an index action that operates on a document.

Fields

\@search\.action? "upload"|"merge"|"mergeOrUpload"|"delete" - The operation to perform on a document in an indexing batch.

azure.ai.search.index: IndexBatch

Contains a batch of document write actions to send to the index.

Fields

value IndexAction[] - The actions in the batch.

azure.ai.search.index: IndexDocumentsResult

Response containing the status of operations for all documents in the indexing request.

Fields

value IndexingResult[] - The list of status information for each document in the indexing request.

azure.ai.search.index: IndexingResult

Status of an indexing operation for a single document.

Fields

'key string - The key of a document that was in the indexing request.

errorMessage? string - The error message explaining why the indexing operation failed for the document identified by the key; null if indexing succeeded.

status boolean - A value indicating whether the indexing operation succeeded for the document identified by the key.

statusCode Signed32 - The status code of the indexing operation. Possible values include: 200 for a successful update or delete, 201 for successful document creation, 400 for a malformed input document, 404 for document not found, 409 for a version conflict, 422 when the index is temporarily unavailable, or 503 for when the service is too busy.

azure.ai.search.index: LookupDocument

A document retrieved via a document lookup operation.

azure.ai.search.index: QueryResultDocumentSubscores

The breakdown of subscores between the text and vector query components of the search query for this document. Each vector query is shown as a separate object in the same order they were received.

Fields

text? TextResult - The BM25 or Classic score for the text portion of the query.

vectors? QueryResultDocumentVectorSubscores[] - The vector similarity and @search.score values for each vector query.

documentBoost? decimal - The BM25 or Classic score for the text portion of the query.

azure.ai.search.index: QueryResultDocumentVectorSubscores

The vector similarity and @search.score values for each vector query. Each cross-field vector query will have separate subscores for each referenced field.

Fields

SingleVectorFieldResult... - Rest field

azure.ai.search.index: SearchDocumentsResult

Response containing search results from an index.

Fields

\@odata\.count? int - The total count of results found by the search operation, or null if the count was not requested. If present, the count may be greater than the number of results in this response. This can happen if you use the $top or $skip parameters, or if the query can't return all the requested documents in a single response.

\@search\.coverage? decimal - A value indicating the percentage of the index that was included in the query, or null if minimumCoverage was not specified in the request.

\@search\.answers? AnswerResult[]? - The answers query results for the search operation; null if the answers query parameter was not specified or set to 'none'.

\@search\.nextPageParameters? SearchRequest - Parameters for filtering, sorting, faceting, paging, and other search query behaviors.

value SearchResult[] - The sequence of results returned by the query.

\@odata\.nextLink? string - Continuation URL returned when the query can't return all the requested results in a single response. You can use this URL to formulate another GET or POST Search request to get the next part of the search response. Make sure to use the same verb (GET or POST) as the request that produced this response.

\@search\.semanticPartialResponseReason? SemanticPartialResponseReason - Reason that a partial response was returned for a semantic ranking request.

\@search\.semanticPartialResponseType? SemanticPartialResponseType - Type of partial response that was returned for a semantic ranking request.

azure.ai.search.index: SearchRequest

Parameters for filtering, sorting, faceting, paging, and other search query behaviors.

Fields

count? boolean - A value that specifies whether to fetch the total count of results. Default is false. Setting this value to true may have a performance impact. Note that the count returned is an approximation.

filter? string - The OData $filter expression to apply to the search query.

highlight? string - The comma-separated list of field names to use for hit highlights. Only searchable fields can be used for hit highlighting.

highlightPostTag? string - A string tag that is appended to hit highlights. Must be set with highlightPreTag. Default is </em>.

highlightPreTag? string - A string tag that is prepended to hit highlights. Must be set with highlightPostTag. Default is <em>.

minimumCoverage? decimal - A number between 0 and 100 indicating the percentage of the index that must be covered by a search query in order for the query to be reported as a success. This parameter can be useful for ensuring search availability even for services with only one replica. The default is 100.

orderby? string - The comma-separated list of OData $orderby expressions by which to sort the results. Each expression can be either a field name or a call to either the geo.distance() or the search.score() functions. Each expression can be followed by asc to indicate ascending, or desc to indicate descending. The default is ascending order. Ties will be broken by the match scores of documents. If no $orderby is specified, the default sort order is descending by document match score. There can be at most 32 $orderby clauses.

queryType? QueryType - Specifies the syntax of the search query. The default is 'simple'. Use 'full' if your query uses the Lucene query syntax.

scoringStatistics? ScoringStatistics - A value that specifies whether we want to calculate scoring statistics (such as document frequency) globally for more consistent scoring, or locally, for lower latency. The default is 'local'. Use 'global' to aggregate scoring statistics globally before scoring. Using global scoring statistics can increase latency of search queries.

sessionId? string - A value to be used to create a sticky session, which can help getting more consistent results. As long as the same sessionId is used, a best-effort attempt will be made to target the same replica set. Be wary that reusing the same sessionID values repeatedly can interfere with the load balancing of the requests across replicas and adversely affect the performance of the search service. The value used as sessionId cannot start with a '_' character.

scoringParameters? string[] - The list of parameter values to be used in scoring functions (for example, referencePointParameter) using the format name-values. For example, if the scoring profile defines a function with a parameter called 'mylocation' the parameter string would be "mylocation--122.2,44.8" (without the quotes).

scoringProfile? string - The name of a scoring profile to evaluate match scores for matching documents in order to sort the results.

debug? QueryDebugMode - Enables a debugging tool that can be used to further explore your search results.

search? string - A full-text search query expression; Use "*" or omit this parameter to match all documents.

searchFields? string - The comma-separated list of field names to which to scope the full-text search. When using fielded search (fieldName:searchExpression) in a full Lucene query, the field names of each fielded search expression take precedence over any field names listed in this parameter.

searchMode? SearchMode - Specifies whether any or all of the search terms must be matched in order to count the document as a match.

'select? string - The comma-separated list of fields to retrieve. If unspecified, all fields marked as retrievable in the schema are included.

skip? Signed32 - The number of search results to skip. This value cannot be greater than 100,000. If you need to scan documents in sequence, but cannot use skip due to this limitation, consider using orderby on a totally-ordered key and filter with a range query instead.

top? Signed32 - The number of search results to retrieve. This can be used in conjunction with $skip to implement client-side paging of search results. If results are truncated due to server-side paging, the response will include a continuation token that can be used to issue another Search request for the next page of results.

semanticConfiguration? string - The name of a semantic configuration that will be used when processing documents for queries of type semantic.

semanticErrorHandling? SemanticErrorHandling - Allows the user to choose whether a semantic call should fail completely, or to return partial results.

semanticMaxWaitInMilliseconds? Signed32? - Allows the user to set an upper bound on the amount of time it takes for semantic enrichment to finish processing before the request fails.

semanticQuery? string - Allows setting a separate search query that will be solely used for semantic reranking, semantic captions and semantic answers. Is useful for scenarios where there is a need to use different queries between the base retrieval and ranking phase, and the L2 semantic phase.

answers? Answers - This parameter is only valid if the query type is semantic. If set, the query returns answers extracted from key passages in the highest ranked documents. The number of answers returned can be configured by appending the pipe character | followed by the count-<number of answers> option after the answers parameter value, such as extractive|count-3. Default count is 1. The confidence threshold can be configured by appending the pipe character | followed by the threshold-<confidence threshold> option after the answers parameter value, such as extractive|threshold-0.9. Default threshold is 0.7.

captions? Captions - This parameter is only valid if the query type is semantic. If set, the query returns captions extracted from key passages in the highest ranked documents. When Captions is set to extractive, highlighting is enabled by default, and can be configured by appending the pipe character | followed by the highlight-<true/false> option, such as extractive|highlight-true. Defaults to None.

vectorQueries? VectorQuery[] - The query parameters for vector and hybrid search queries.

vectorFilterMode? VectorFilterMode - Determines whether or not filters are applied before or after the vector search is performed.

azure.ai.search.index: SearchResult

Contains a document found by a search query, plus associated metadata.

Fields

\@search\.score decimal - The relevance score of the document compared to other documents returned by the query.

\@search\.rerankerScore? decimal? - The relevance score computed by the semantic ranker for the top search results. Search results are sorted by the RerankerScore first and then by the Score. RerankerScore is only returned for queries of type 'semantic'.

\@search\.rerankerBoostedScore? decimal? - The relevance score computed by boosting the Reranker Score. Search results are sorted by the RerankerScore/RerankerBoostedScore based on useScoringProfileBoostedRanking in the Semantic Config. RerankerBoostedScore is only returned for queries of type 'semantic'

\@search\.highlights? record { string[]... } - Text fragments from the document that indicate the matching search terms, organized by each applicable field; null if hit highlighting was not enabled for the query.

\@search\.captions? CaptionResult[]? - Captions are the most representative passages from the document relatively to the search query. They are often used as document summary. Captions are only returned for queries of type 'semantic'.

\@search\.documentDebugInfo? DocumentDebugInfo - Contains debugging information that can be used to further explore your search results.

azure.ai.search.index: SingleVectorFieldResult

A single vector field result. Both @search.score and vector similarity values are returned. Vector similarity is related to @search.score by an equation.

Fields

searchScore? decimal - The @search.score value that is calculated from the vector similarity score. This is the score that's visible in a pure single-field single-vector query.

vectorSimilarity? decimal - The vector similarity score for this document. Note this is the canonical definition of similarity metric, not the 'distance' version. For example, cosine similarity instead of cosine distance.

azure.ai.search.index: SuggestDocumentsResult

Response containing suggestion query results from an index.

Fields

value SuggestResult[] - The sequence of results returned by the query.

\@search\.coverage? decimal - A value indicating the percentage of the index that was included in the query, or null if minimumCoverage was not set in the request.

azure.ai.search.index: SuggestRequest

Parameters for filtering, sorting, fuzzy matching, and other suggestions query behaviors.

Fields

filter? string - An OData expression that filters the documents considered for suggestions.

fuzzy? boolean - A value indicating whether to use fuzzy matching for the suggestion query. Default is false. When set to true, the query will find suggestions even if there's a substituted or missing character in the search text. While this provides a better experience in some scenarios, it comes at a performance cost as fuzzy suggestion searches are slower and consume more resources.

highlightPostTag? string - A string tag that is appended to hit highlights. Must be set with highlightPreTag. If omitted, hit highlighting of suggestions is disabled.

highlightPreTag? string - A string tag that is prepended to hit highlights. Must be set with highlightPostTag. If omitted, hit highlighting of suggestions is disabled.

minimumCoverage? decimal - A number between 0 and 100 indicating the percentage of the index that must be covered by a suggestion query in order for the query to be reported as a success. This parameter can be useful for ensuring search availability even for services with only one replica. The default is 80.

orderby? string - The comma-separated list of OData $orderby expressions by which to sort the results. Each expression can be either a field name or a call to either the geo.distance() or the search.score() functions. Each expression can be followed by asc to indicate ascending, or desc to indicate descending. The default is ascending order. Ties will be broken by the match scores of documents. If no $orderby is specified, the default sort order is descending by document match score. There can be at most 32 $orderby clauses.

search string - The search text to use to suggest documents. Must be at least 1 character, and no more than 100 characters.

searchFields? string - The comma-separated list of field names to search for the specified search text. Target fields must be included in the specified suggester.

'select? string - The comma-separated list of fields to retrieve. If unspecified, only the key field will be included in the results.

suggesterName string - The name of the suggester as specified in the suggesters collection that's part of the index definition.

top? Signed32 - The number of suggestions to retrieve. This must be a value between 1 and 100. The default is 5.

azure.ai.search.index: SuggestResult

A result containing a document found by a suggestion query, plus associated metadata.

Fields

\@search\.text string - The text of the suggestion result.

azure.ai.search.index: TextResult

The BM25 or Classic score for the text portion of the query.

Fields

searchScore? decimal - The BM25 or Classic score for the text portion of the query.

azure.ai.search.index: VectorQuery

The query parameters for vector and hybrid search queries.

Fields

kind VectorQueryKind - The kind of vector query being performed.

k? Signed32 - Number of nearest neighbors to return as top hits.

fields? string - Vector Fields of type Collection(Edm.Single) to be included in the vector searched.

exhaustive? boolean - When true, triggers an exhaustive k-nearest neighbor search across all vectors within the vector index. Useful for scenarios where exact matches are critical, such as determining ground truth values.

oversampling? decimal - Oversampling factor. Minimum value is 1. It overrides the 'defaultOversampling' parameter configured in the index definition. It can be set only when 'rerankWithOriginalVectors' is true. This parameter is only permitted when a compression method is used on the underlying vector field.

weight? float - Relative weight of the vector query when compared to other vector query and/or the text query within the same search request. This value is used when combining the results of multiple ranking lists produced by the different vector queries and/or the results retrieved through the text query. The higher the weight, the higher the documents that matched that query will be in the final ranking. Default is 1.0 and the value needs to be a positive number larger than zero.

azure.ai.search.index: VectorsDebugInfo

Fields

subscores? QueryResultDocumentSubscores - The breakdown of subscores between the text and vector query components of the search query for this document. Each vector query is shown as a separate object in the same order they were received.

Union types

azure.ai.search.index: ScoringStatistics

"local"|"global"

ScoringStatistics

A value that specifies whether we want to calculate scoring statistics (such as document frequency) globally for more consistent scoring, or locally, for lower latency. The default is 'local'. Use 'global' to aggregate scoring statistics globally before scoring. Using global scoring statistics can increase latency of search queries.

azure.ai.search.index: QueryDebugMode

"disabled"|"vector"

QueryDebugMode

Enables a debugging tool that can be used to further explore your search results.

azure.ai.search.index: VectorQueryKind

"vector"|"text"

VectorQueryKind

The kind of vector query being performed.

azure.ai.search.index: VectorFilterMode

"postFilter"|"preFilter"

VectorFilterMode

Determines whether or not filters are applied before or after the vector search is performed.

azure.ai.search.index: Captions

"none"|"extractive"

Captions

This parameter is only valid if the query type is semantic. If set, the query returns captions extracted from key passages in the highest ranked documents. When Captions is set to extractive, highlighting is enabled by default, and can be configured by appending the pipe character | followed by the highlight-<true/false> option, such as extractive|highlight-true. Defaults to None.

azure.ai.search.index: QueryType

"simple"|"full"|"semantic"

QueryType

Specifies the syntax of the search query. The default is 'simple'. Use 'full' if your query uses the Lucene query syntax.

azure.ai.search.index: SemanticPartialResponseReason

"maxWaitExceeded"|"capacityOverloaded"|"transient"

SemanticPartialResponseReason

Reason that a partial response was returned for a semantic ranking request.

azure.ai.search.index: Answers

"none"|"extractive"

Answers

This parameter is only valid if the query type is semantic. If set, the query returns answers extracted from key passages in the highest ranked documents. The number of answers returned can be configured by appending the pipe character | followed by the count-<number of answers> option after the answers parameter value, such as extractive|count-3. Default count is 1. The confidence threshold can be configured by appending the pipe character | followed by the threshold-<confidence threshold> option after the answers parameter value, such as extractive|threshold-0.9. Default threshold is 0.7.

azure.ai.search.index: AutocompleteMode

"oneTerm"|"twoTerms"|"oneTermWithContext"

AutocompleteMode

Specifies the mode for Autocomplete. The default is 'oneTerm'. Use 'twoTerms' to get shingles and 'oneTermWithContext' to use the current context in producing autocomplete terms.

azure.ai.search.index: SemanticErrorHandling

"partial"|"fail"

SemanticErrorHandling

Allows the user to choose whether a semantic call should fail completely, or to return partial results.

azure.ai.search.index: SemanticPartialResponseType

"baseResults"|"rerankedResults"

SemanticPartialResponseType

Type of partial response that was returned for a semantic ranking request.

azure.ai.search.index: SearchMode

"any"|"all"

SearchMode

Specifies whether any or all of the search terms must be matched in order to count the document as a match.

Simple name reference types

azure.ai.search.index: docs_search_post_search_body

SearchRequest

docs_search_post_search_body

The Search request.

Import

import ballerinax/azure.ai.search.index;

Other versions

1.0.2

1.0.1 1.0.0

Metadata

Released date: 16 days ago

Version: 1.0.2

License: Apache-2.0

Compatibility

Platform: any

Ballerina version: 2201.12.0

GraalVM compatible: Yes

Pull count

Total: 814

Current verison: 14

Weekly downloads

Source repository

Keywords

AI/Search

Azure

Search Index

Azure AI Search

Vendor/Microsoft

Area/AI & Machine Learning

Type/Connector

Contributors

Dependencies

ballerina/constraint/1.7.0 ballerina/log/2.14.0 ballerina/data.jsondata/1.1.3

Cookie policy

Delete policy

clients

records

unionTypes

simpleNameReferenceTypes

ballerinax/azure.ai.search.index Ballerina library

Overview

Key Features

Setup guide

Create an Azure AI Search Service

Quickstart

Step 1: Import the module

Step 2: Create a new connector instance

Step 3: Invoke the connector operation

Search for documents in an index

Step 4: Run the Ballerina application

Examples

Clients

azure.ai.search.index: Client

Constructor

documentsCount

Parameters

documentsSearchGet

Parameters

Return Type

documentsSearchPost

Parameters

Return Type

documentsGet

Parameters

Return Type

documentsSuggestGet

Parameters

Return Type

documentsSuggestPost

Parameters

Return Type

documentsIndex

Parameters

Return Type

documentsAutocompleteGet

Parameters

Return Type

documentsAutocompletePost

Parameters

Return Type

Records

azure.ai.search.index: AnswerResult

Fields

azure.ai.search.index: AutocompleteItem

Fields

azure.ai.search.index: AutocompleteRequest

Fields

azure.ai.search.index: AutocompleteResult

Fields

azure.ai.search.index: CaptionResult

Fields

azure.ai.search.index: ConnectionConfig

Fields

azure.ai.search.index: DocumentDebugInfo

Fields

azure.ai.search.index: DocumentsAutocompleteGetHeaders

Fields

azure.ai.search.index: DocumentsAutocompleteGetQueries

Fields

azure.ai.search.index: DocumentsAutocompletePostHeaders

Fields

azure.ai.search.index: DocumentsAutocompletePostQueries

Fields

azure.ai.search.index: DocumentsCountHeaders

Fields

azure.ai.search.index: DocumentsCountQueries

Fields

azure.ai.search.index: DocumentsGetHeaders

Fields

azure.ai.search.index: DocumentsGetQueries

Fields

azure.ai.search.index: DocumentsIndexHeaders

Fields

azure.ai.search.index: DocumentsIndexQueries

Fields