Ballerina Azure AI Search Index connector

Overview

Azure AI Search, a cloud search service with built-in AI capabilities, provides the Azure AI Search REST API to access its powerful search and indexing functionality for building rich search experiences.

The ballarinax/azure.ai.search.index package offers functionality to connect and interact with Azure AI Search Index Management REST API enabling seamless interaction with search indexes, documents, and search operations for building intelligent search applications.

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 here.

Create an Azure AI Search Service

1. Open the Azure Portal.

2. Navigate to AI search.

3. Fill in the required details:

   • Resource group
   • Service name
   • Location
   • Pricing tier

4. Review and create the search service.

5. Once the service is deployed, navigate to the service and obtain the service URL and Admin API keys from the "Keys" section.

6. Store the service URL and API key securely to use in your application.

7. Create a search index and add documents to it. Refer to the Azure AI Search documentation for detailed instructions.

8. Ensure that your search index is properly configured with searchable fields, key fields, and suggesters as needed for your application.

9. Test your search index using the Azure Portal or REST API to ensure it is functioning as expected before integrating it with your Ballerina 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:

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

Build from the source

Setting up the prerequisites

1. Download and install Java SE Development Kit (JDK) version 17. You can download it from either of the following sources:

   • Oracle JDK
   • OpenJDK

   Note: After installation, remember to set the JAVA_HOME environment variable to the directory where JDK was installed.

2. Download and install Ballerina Swan Lake.

3. Download and install Docker.

   Note: Ensure that the Docker daemon is running before executing any tests.

4. Export Github Personal access token with read package permissions as follows,

   export packageUser=<Username>
   export packagePAT=<Personal access token>

Build options

Execute the commands below to build from the source.

1. To build the package:

   ./gradlew clean build

2. To run the tests:

   ./gradlew clean test

3. To build the without the tests:

   ./gradlew clean build -x test

4. To run tests against different environments:

   ./gradlew clean test -Pgroups=<Comma separated groups/test cases>

5. To debug the package with a remote debugger:

   ./gradlew clean build -Pdebug=<port>

6. To debug with the Ballerina language:

   ./gradlew clean build -PbalJavaDebug=<port>

7. Publish the generated artifacts to the local Ballerina Central repository:

   ./gradlew clean build -PpublishToLocalCentral=true

8. Publish the generated artifacts to the Ballerina Central repository:

   ./gradlew clean build -PpublishToCentral=true

Contribute to Ballerina

As an open-source project, Ballerina welcomes contributions from the community.

For more information, go to the contribution guidelines.

Code of conduct

All the contributors are encouraged to read the Ballerina Code of Conduct.

Useful links

• For more information go to the azure.ai.search.index package.
• For example demonstrations of the usage, go to Ballerina By Examples.
• Chat live with us via our Discord server.
• Post all technical questions on Stack Overflow with the #ballerina tag.