diff --git a/docs/scalardb-cluster/getting-started-with-vector-search.mdx b/docs/scalardb-cluster/getting-started-with-vector-search.mdx index 97871551..d68f09ae 100644 --- a/docs/scalardb-cluster/getting-started-with-vector-search.mdx +++ b/docs/scalardb-cluster/getting-started-with-vector-search.mdx @@ -7,7 +7,11 @@ displayed_sidebar: docsEnglish # Getting Started with ScalarDB Cluster for Vector Search -ScalarDB Cluster provides a vector store abstraction to help applications interact with vector stores (embedding stores) in a unified way. This page explains what the feature is and why it is beneficial to users. +import WarningLicenseKeyContact from '/src/components/en-us/_warning-license-key-contact.mdx'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +ScalarDB Cluster provides a vector store abstraction to help applications interact with vector stores (embedding stores) in a unified way. This getting-started tutorial explains how to run vector search in ScalarDB Cluster. ## What is the vector store abstraction? @@ -35,7 +39,446 @@ In the era of generative AI, one of the challenges organizations face when deplo RAG relies on vector stores, which are typically created by extracting data from databases, converting that data into vectors, and then loading those vectors. By using vector store and database abstraction in ScalarDB Cluster, you can implement the entire process seamlessly. This approach significantly simplifies the workflow and code, eliminating the need to write complex applications that depend on specific vector stores and databases. +## Tutorial + +This tutorial explains how to run vector search in ScalarDB Cluster. + +### Prerequisites + +- OpenJDK LTS version (8, 11, 17, or 21) from [Eclipse Temurin](https://adoptium.net/temurin/releases/) +- [Docker](https://www.docker.com/get-started/) 20.10 or later with [Docker Compose](https://docs.docker.com/compose/install/) V2 or later + +:::note + +This tutorial has been tested with OpenJDK from Eclipse Temurin. ScalarDB itself, however, has been tested with JDK distributions from various vendors. For details about the requirements for ScalarDB, including compatible JDK distributions, please see [Requirements](../requirements.mdx). + +::: + + + +### 1. Create the ScalarDB Cluster configuration file + +Create the following configuration file as `scalardb-cluster-node.properties`, replacing `` and `` with your ScalarDB license key and license check certificate values. For more information about the license key and certificate, see [How to Configure a Product License Key](../scalar-licensing/README.mdx). + +```yaml +# Storage configurations +scalar.db.storage=jdbc +scalar.db.contact_points=jdbc:postgresql://postgresql:5432/postgres +scalar.db.username=postgres +scalar.db.password=postgres + +# Enable the standalone mode +scalar.db.cluster.node.standalone_mode.enabled=true + +# Enable the embedding feature +scalar.db.embedding.enabled=true + +# License key configurations +scalar.db.cluster.node.licensing.license_key= +scalar.db.cluster.node.licensing.license_check_cert_pem= +``` + +Additionally, you need to add the properties for the embedding store and the embedding model to the configuration file, depending on the embedding store and the embedding model you want to use. + +Select the embedding store that you want to use, and follow the instructions to configure it. + + + + The in-memory embedding store is a basic in-memory implementation. This embedding store is useful for fast prototyping and simple use cases. + + To use the in-memory embedding store, add the following property to the configuration file: + + ```properties + scalar.db.embedding.store.type=in-memory + ``` + + + The OpenSearch embedding store is an embedding store that uses OpenSearch as the backend. + + Select whether your OpenSearch implementation is running locally or running on AWS, and follow the instructions to configure it. + + + + For OpenSearch clusters that are running locally and are reachable on the network, add the following properties to the configuration file: + + ```properties + scalar.db.embedding.store.type=opensearch + + # OpenSearch Server URL. + scalar.db.embedding.store.opensearch.server_url= + + # OpenSearch API key (optional). + scalar.db.embedding.store.opensearch.api_key= + + # OpenSearch username (optional). + scalar.db.embedding.store.opensearch.user_name= + + # OpenSearch password (optional). + scalar.db.embedding.store.opensearch.password= + + # OpenSearch index name. + scalar.db.embedding.store.opensearch.index_name= + ``` + + + For OpenSearch clusters that are running as a fully managed service on AWS, add the following properties to the configuration file: + + ```properties + scalar.db.embedding.store.type=opensearch + + # OpenSearch Server URL. + scalar.db.embedding.store.opensearch.server_url= + + # The AWS signing service name, one of `es` (Amazon OpenSearch) or `aoss` (Amazon OpenSearch Serverless). + scalar.db.embedding.store.opensearch.service_name= + + # The AWS region for which requests will be signed. This should typically match the region in `server_url`. + scalar.db.embedding.store.opensearch.region= + + # The AWS access key ID. + scalar.db.embedding.store.opensearch.access_key_id= + + # The AWS secret access key. + scalar.db.embedding.store.opensearch.secret_access_key= + + # OpenSearch index name. + scalar.db.embedding.store.opensearch.index_name= + ``` + + + + + The Azure Cosmos DB for NoSQL embedding store is an embedding store that uses Azure Cosmos DB as the backend. + + To use the Azure Cosmos DB for NoSQL embedding store, add the following properties to the configuration file: + + ```properties + scalar.db.embedding.store.type=azure-cosmos-nosql + + # The Azure Cosmos DB endpoint that the SDK will connect to. + scalar.db.embedding.store.azure-cosmos-nosql.endpoint= + + # A master key used to perform authentication for accessing resources. A read-only key can also be used only for read-only operations. + scalar.db.embedding.store.azure-cosmos-nosql.key= + + # The database name to be used. + scalar.db.embedding.store.azure-cosmos-nosql.database_name= + + # The container name to be used. + scalar.db.embedding.store.azure-cosmos-nosql.container_name= + ``` + + + The Azure AI Search embedding store is an embedding store that uses Azure AI Search as the backend. + + To use the Azure AI Search embedding store, add the following properties to the configuration file: + + ```properties + scalar.db.embedding.store.type=azure-ai-search + # The Azure AI Search endpoint. + scalar.db.embedding.store.azure-ai-search.endpoint= + + # The Azure AI Search API key. + scalar.db.embedding.store.azure-ai-search.api_key= + + # The name of the index to be used. If no index is provided, the name of the default index to be used. + scalar.db.embedding.store.azure-ai-search.index_name= + ``` + + + The pgvector embedding store is an embedding store that uses pgvector, which is a Postgres extension for vector similarity search, as the backend. + + To use the pgvector embedding store, add the following properties to the configuration file: + + ```properties + scalar.db.embedding.store.type=pgvector + + # The database host. + scalar.db.embedding.store.pgvector.host= + + # The database port. + scalar.db.embedding.store.pgvector.port= + + # The database user. + scalar.db.embedding.store.pgvector.user= + + # The database password. + scalar.db.embedding.store.pgvector.password= + + # The database name. + scalar.db.embedding.store.pgvector.database= + + # The table name. + scalar.db.embedding.store.pgvector.table= + ``` + + + +Select the embedding model that you want to use, and follow the instructions to configure it. + + + + The in-process embedding model is a local embedding model powered by ONNX runtime and is running in the ScalarDB Cluster process. This embedding model is useful for fast prototyping and simple use cases. + + To use the in-process embedding model, add the following property to the configuration file: + + ```properties + scalar.db.embedding.model.type=in-process + ``` + + + The Amazon Bedrock embedding model is an embedding model that uses Amazon Bedrock as the backend. + + To use the Amazon Bedrock embedding model, add the following properties to the configuration file: + + ```properties + scalar.db.embedding.model.type=bedrock-titan + + # The AWS region for which requests will be signed. + scalar.db.embedding.model.bedrock-titan.region= + + # The AWS access key ID. + scalar.db.embedding.model.bedrock-titan.access_key_id= + + # The AWS secret access key. + scalar.db.embedding.model.bedrock-titan.secret_access_key= + + # The model. Either `amazon.titan-embed-text-v1` or `amazon.titan-embed-text-v2:0`. + scalar.db.embedding.model.bedrock-titan.model= + + # The dimensions. + scalar.db.embedding.model.bedrock-titan.dimensions= + ``` + + + The Azure OpenAI embedding model is an embedding model that uses Azure OpenAI as the backend. + + To use the Azure OpenAI embedding model, add the following properties to the configuration file: + + ```properties + scalar.db.embedding.model.type=azure-open-ai + + # The Azure OpenAI endpoint. + scalar.db.embedding.model.azure-open-ai.endpoint= + + # The Azure OpenAI API key. + scalar.db.embedding.model.azure-open-ai.api_key= + + # The deployment name in Azure OpenAI. + scalar.db.embedding.model.azure-open-ai.deployment_name= + + # The dimensions. + scalar.db.embedding.model.azure-open-ai.dimensions= + ``` + + + The Google Vertex AI embedding model is an embedding model that uses Google Vertex AI as the backend. + + To use the Google Vertex AI embedding model, add the following properties to the configuration file: + + ```properties + scalar.db.embedding.model.type=vertex-ai + + # The Google Cloud project. + scalar.db.embedding.model.vertex-ai.project= + + # The Google Cloud location. + scalar.db.embedding.model.vertex-ai.location= + + # The endpoint. + scalar.db.embedding.model.vertex-ai.endpoint= + + # The publisher. + scalar.db.embedding.model.vertex-ai.publisher= + + # The model name. + scalar.db.embedding.model.vertex-ai.model_name= + + # The output dimensionality. + scalar.db.embedding.model.vertex-ai.output_dimensionality= + ``` + + + The OpenAI embedding model is an embedding model that uses OpenAI as the backend. + + To use the OpenAI embedding model, add the following properties to the configuration file: + + ```properties + scalar.db.embedding.model.type=open-ai + + # The OpenAI API key. + scalar.db.embedding.model.open-ai.api_key= + + # The model name. + scalar.db.embedding.model.open-ai.model_name= + + # The base URL. + scalar.db.embedding.model.open-ai.base_url= + + # The organization ID. + scalar.db.embedding.model.open-ai.organization_id= + + # The dimensions. + scalar.db.embedding.model.open-ai.dimensions= + + # The user. + scalar.db.embedding.model.open-ai.user= + ``` + + + +### 2. Create the Docker Compose file + +Create the following configuration file as `docker-compose.yaml`. + +```yaml +services: + postgresql: + container_name: "postgresql" + image: "postgres:15" + ports: + - 5432:5432 + environment: + - POSTGRES_PASSWORD=postgres + healthcheck: + test: ["CMD-SHELL", "pg_isready || exit 1"] + interval: 1s + timeout: 10s + retries: 60 + start_period: 30s + + scalardb-cluster-standalone: + container_name: "scalardb-cluster-node" + image: "ghcr.io/scalar-labs/scalardb-cluster-node-byol-premium:3.15.2" + ports: + - 60053:60053 + - 9080:9080 + volumes: + - ./scalardb-cluster-node.properties:/scalardb-cluster/node/scalardb-cluster-node.properties + depends_on: + postgresql: + condition: service_healthy +``` + +### 3. Start PostgreSQL and ScalarDB Cluster + +Run the following command to start PostgreSQL and ScalarDB Cluster in standalone mode. + +```console +docker compose up -d +``` + +It may take a few minutes for ScalarDB Cluster to fully start. + +### 4. Add the Java Client SDK for the embedding store abstraction to your project + +The ScalarDB Cluster Embedding Java Client SDK library is available on the [Maven Central Repository](https://mvnrepository.com/artifact/com.scalar-labs/scalardb-cluster-embedding-java-client-sdk). You can add the library as a build dependency to your application by using Gradle or Maven. + +Select your build tool, and follow the instructions to add the build dependency for the ScalarDB Cluster Embedding Java Client SDK to your application. + + + + To add the build dependency for the ScalarDB Cluster Embedding Java Client SDK by using Gradle, add the following to `build.gradle` in your application: + + ```gradle + dependencies { + implementation 'com.scalar-labs:scalardb-cluster-embedding-java-client-sdk:3.15.2' + } + ``` + + + To add the build dependency for the ScalarDB Cluster Embedding Java Client SDK by using Maven, add the following to `pom.xml` in your application: + + ```xml + + com.scalar-labs + scalardb-cluster-embedding-java-client-sdk + 3.15.2 + + ``` + + + +### 5. Run the sample code + +Create a new Java class and add the following code to run the sample code. + +```java +try (ScalarDbEmbeddingClientFactory scalarDbEmbeddingClientFactory = + ScalarDbEmbeddingClientFactory.builder() + .withProperty("scalar.db.embedding.client.contact_points", "indirect:localhost") + .build()) { + // Create an embedding store and an embedding model. + EmbeddingStore scalarDbEmbeddingStore = + scalarDbEmbeddingClientFactory.createEmbeddingStore(); + EmbeddingModel scalarDbEmbeddingModel = scalarDbEmbeddingClientFactory.createEmbeddingModel(); + + // Add embeddings to the embedding store. + TextSegment segment1 = TextSegment.from("I like football."); + Embedding embedding1 = scalarDbEmbeddingModel.embed(segment1).content(); + scalarDbEmbeddingStore.add(embedding1, segment1); + + TextSegment segment2 = TextSegment.from("The weather is good today."); + Embedding embedding2 = scalarDbEmbeddingModel.embed(segment2).content(); + scalarDbEmbeddingStore.add(embedding2, segment2); + + // Search for embeddings. + Embedding queryEmbedding = + scalarDbEmbeddingModel.embed("What is your favourite sport?").content(); + EmbeddingSearchResult result = + scalarDbEmbeddingStore.search( + EmbeddingSearchRequest.builder() + .queryEmbedding(queryEmbedding) + .maxResults(1) + .build()); + + // Print the search result. + List> matches = result.matches(); + EmbeddingMatch embeddingMatch = matches.get(0); + System.out.println(embeddingMatch.embedded().text()); + System.out.println(embeddingMatch.score()); +} +``` + +This sample code demonstrates how to create an embedding store and an embedding model, add embeddings to the embedding store, and search for embeddings. + +Except for the part of the code that creates an embedding store and an embedding model, the usage is the same as LangChain4j. For more information about LangChain4j, see the following: +- [LangChain4j](https://docs.langchain4j.dev/) +- [Embedding Model](https://docs.langchain4j.dev/tutorials/rag#embedding-model) +- [Embedding Store](https://docs.langchain4j.dev/tutorials/rag#embedding-store) + +#### About `ScalarDbEmbeddingClientFactory` + +As shown in the code snippet, the `ScalarDbEmbeddingClientFactory` class provides a builder to create an instance of the factory. The builder allows you to set properties for the factory. In this example, the `withProperty()` method is used to set the contact points for the factory as follows: + +```java +ScalarDbEmbeddingClientFactory scalarDbEmbeddingClientFactory = ScalarDbEmbeddingClientFactory.builder() + .withProperty("scalar.db.embedding.client.contact_points", "indirect:localhost") + .build(); +``` + +You can also set a properties file by using the `withPropertiesFile()` method. + +Then, you can create an embedding store and an embedding model by using the factory as follows: + +```java +EmbeddingStore scalarDbEmbeddingStore = + scalarDbEmbeddingClientFactory.createEmbeddingStore(); +EmbeddingModel scalarDbEmbeddingModel = scalarDbEmbeddingClientFactory.createEmbeddingModel(); +``` + +Their methods internally connect to ScalarDB Cluster, which interacts with the embedding store by using the embedding model, both of which are specified in the configuration. + +You should reuse the `scalarDbEmbeddingStore` and `scalarDbEmbeddingModel` instances to interact with vector stores in an application. + +:::note + +The `ScalarDbEmbeddingClientFactory` instance should be closed after use to release the connection to ScalarDB Cluster. + +::: + ## Additional details The vector search feature is currently in Private Preview. For more details, please [contact us](https://www.scalar-labs.com/contact) or wait for this feature to become publicly available in a future version. +- [Javadoc](https://javadoc.io/doc/com.scalar-labs/scalardb-cluster-embedding-java-client-sdk/3.15.2/index.html)