SQL Server

The SQL Server Embedding Store integrates with the Vector search and vector indexes introduced in SQL Server 2025.

Maven Dependency

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-community-sqlserver</artifactId>
    <version>${latest version here}</version>
</dependency>

APIs

• SQLServerEmbeddingStore

Usage

Instances of this store can be created by configuring a builder. The builder requires that a DataSource and an embedding table be provided.

It is recommended to configure a DataSource which pools connections, such as the Universal Connection Pool or Hikari. A connection pool will avoid the latency of repeatedly creating new database connections.

Examples of Embedding Store Configuration

If an embedding table already exists in your database, provide the table configuration:

EmbeddingStore<TextSegment> embeddingStore = SQLServerEmbeddingStore.dataSourceBuilder()
   .dataSource(myDataSource)
   .embeddingTable(EmbeddingTable.builder()
           .name("my_embedding_table")
           .dimension(384) // Must specify dimension
           .build())
   .build();

If the table does not already exist, it can be created by setting the create option:

EmbeddingStore<TextSegment> embeddingStore = SQLServerEmbeddingStore.dataSourceBuilder()
   .dataSource(myDataSource)
   .embeddingTable(EmbeddingTable.builder()
           .name("my_embedding_table")
           .createOption(CreateOption.CREATE)
           .dimension(384) 
           .build())
   .build();

The previous option will fail if the table already exists. In that case, you can use the CREATE_IF_NOT_EXISTS option:

EmbeddingStore<TextSegment> embeddingStore = SQLServerEmbeddingStore.dataSourceBuilder()
   .dataSource(myDataSource)
   .embeddingTable(EmbeddingTable.builder()
           .name("my_embedding_table")
           .createOption(CreateOption.CREATE_IF_NOT_EXISTS)
           .dimension(384) 
           .build())
   .build();

Finally, If you want to recreate the table, you can use the CREATE_OR_REPLACE option:

EmbeddingStore<TextSegment> embeddingStore = SQLServerEmbeddingStore.dataSourceBuilder()
   .dataSource(myDataSource)
   .embeddingTable(EmbeddingTable.builder()
           .name("my_embedding_table")
           .createOption(CreateOption.CREATE_OR_REPLACE)
           .dimension(384) 
           .build())
   .build();

If the columns of your existing table do not match the predefined column names or you would like to use different column names, you can customize the table configuration:

SQLServerEmbeddingStore embeddingStore =
SQLServerEmbeddingStore.dataSourceBuilder()
    .dataSource(myDataSource)
    .embeddingTable(EmbeddingTable.builder()
            .createOption(CreateOption.CREATE_OR_REPLACE)
            .name("my_embedding_table")
            .idColumn("id_column_name")
            .embeddingColumn("embedding_column_name")
            .textColumn("text_column_name")
            .metadataColumn("metadata_column_name")
            .dimension(1024)
            .build())
    .build();

You can also configure the SQL Server connection directly without providing a DataSource:

SQLServerEmbeddingStore embeddingStore =
SQLServerEmbeddingStore.connectionBuilder()
    .host("localhost")
    .port(1433)
    .database("MyDatabase")
    .userName("myuser")
    .password("mypassword")
    .embeddingTable(EmbeddingTable.builder()
            .name("embeddings")
            .createOption(CreateOption.CREATE_OR_REPLACE)
            .dimension(384)
            .build())
    .build();

Embeddings table schema

By default, the embedding table will have the following columns:

Name	Type	Description
id	NVARCHAR(36)	Primary key. Used to store UUID strings which are generated when the embedding store
embedding	VECTOR(dimension)	Stores the embedding using SQL Server 2025 native vector type
text	NVARCHAR(MAX)	Stores the text segment
metadata	JSON	Stores the metadata using SQL Server 2025 native JSON data type

Half-Precision (float16) Support

Motivation

Standard float32 vectors in SQL Server are limited to 1998 dimensions. This means that embedding models producing vectors with more than 1998 dimensions (such as OpenAI's text-embedding-3-large with up to 3072 dimensions) cannot be stored using the default vector type.

To overcome this limitation, SQL Server supports half-precision (float16) vectors, which allow storing vectors with higher dimensions. See the Microsoft documentation on half-precision vectors and the JDBC driver documentation for more details.

Requirements

• Preview features must be enabled in the SQL Server database to use half-precision vectors.
• The JDBC driver property vectorTypeSupport must be set to v2.

Configuration

The halfPrecision parameter on EmbeddingTable controls whether half-precision vectors are used:

• HalfPrecisionConfiguration.OFF (Default): Forces the use of float32 vectors. Note that the table creation will fail if the dimension is greater than 1998.
• HalfPrecisionConfiguration.ON: Forces the use of float16 vectors.
• HalfPrecisionConfiguration.AUTO: Uses float32 by default, but automatically switches to float16 if the configured dimension is greater than 1998.

EmbeddingStore<TextSegment> embeddingStore = SQLServerEmbeddingStore.dataSourceBuilder()
   .dataSource(myDataSource)
   .embeddingTable(EmbeddingTable.builder()
           .name("my_large_embedding_table")
           .dimension(3072)
           .halfPrecision(HalfPrecisionConfiguration.ON)
           .build())
   .build();

Limitations

• Half-precision vector support is currently only available for Azure SQL databases.
• Using half-precision vectors may lead to a loss of precision compared to float32 vectors.

Important Notes

Numeric Types

All number values are written as JSON Strings in the metadata fields to avoid overflow issues with numbers as Long.MAX_VALUE.

Vector Storage and Similarity

SQL Server 2025+ supports native VECTOR data types and this module uses the VECTOR_DISTANCE similarity function. This module supports the following metrics for the VECTOR_DISTANCE function:

• COSINE: Cosine similarity (default)
• EUCLIDEAN: Euclidean distance. The euclidean metric needs to perform some additional calculations to get the score from the distance.

JSON Metadata Support

SQL Server 2025 provides native JSON data type support and JSON indexing capabilities. The module uses the native JSON data type for metadata storage and supports creating JSON indexes for optimized metadata filtering using JSON_VALUE function.

You can configure JSON index creation for specific metadata keys, optionally indicating the order of the keys:

EmbeddingTable embeddingTable = EmbeddingTable.builder()
    .name("test_table")
    .createOption(CreateOption.CREATE_OR_REPLACE)
    .dimension(4)
    .build();

SQLServerEmbeddingStore embeddingStore =
    SQLServerEmbeddingStore.dataSourceBuilder()
        .dataSource(myDataSource)
        .embeddingTable(embeddingTable)
        .addIndex(Index.jsonIndexBuilder()
            .createOption(CreateOption.CREATE_OR_REPLACE)
            .key("author", String.class, JSONIndexBuilder.Order.ASC)
            .key("year", Integer.class)
            .build()
        )
        .build();

• Indexes created with Index.jsonIndexBuilder() do not support the CreateOption.CREATE_IF_NOT_EXISTS option.

Limitations

• Vector indexing performance depends on data size and distribution
• DiskANN indexes on the vector column are not supported
• The database collation should be set to a case-sensitive collation for metadata case-sensitive string comparisons
• Distance DOT metric is not supported