Using the SQLite Vector Store connector (Preview)

Overview

The SQLite Vector Store connector can be used to access and manage data in SQLite. The connector has the following characteristics.

Limitations

SQLite doesn't support vector search out-of-the-box. The SQLite extension should be loaded first to enable vector search capability. The current implementation of the SQLite connector is compatible with the sqlite-vec vector search extension.

In order to install the extension, use one of the releases with the specific extension version of your choice. It's possible to get a pre-compiled version with the install.sh script. This script will produce vec0.dll, which must be located in the same folder as the running application. This will allow the application to call the SqliteConnection.LoadExtension("vec0") method and load the vector search extension.

Getting started

Add the SQLite Vector Store connector NuGet package to your project.

dotnet add package Microsoft.SemanticKernel.Connectors.Sqlite --prerelease

You can add the vector store to the IServiceCollection dependency injection container using extension methods provided by Semantic Kernel.

In this case, an instance of the Microsoft.Data.Sqlite.SqliteConnection class will be initialized, the connection will be opened and the vector search extension will be loaded. The default vector search extension name is vec0, but it can be overridden by using the SqliteVectorStoreOptions.VectorSearchExtensionName property.

using Microsoft.SemanticKernel;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSqliteVectorStore("Data Source=:memory:");

Extension methods that take no parameters are also provided. These require an instance of the Microsoft.Data.Sqlite.SqliteConnection class to be separately registered with the dependency injection container.

In this case, the connection will be opened only if it wasn't opened before and the extension method will assume that the vector search extension was already loaded for the registered Microsoft.Data.Sqlite.SqliteConnection instance.

using Microsoft.Data.Sqlite;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<SqliteConnection>(sp => 
{
    var connection = new SqliteConnection("Data Source=:memory:");

    connection.LoadExtension("vector-search-extension-name");

    return connection;
});

builder.Services.AddSqliteVectorStore();

You can construct a SQLite Vector Store instance directly.

using Microsoft.Data.Sqlite;
using Microsoft.SemanticKernel.Connectors.Sqlite;

var connection = new SqliteConnection("Data Source=:memory:");

connection.LoadExtension("vector-search-extension-name");

var vectorStore = new SqliteVectorStore(connection);

It is possible to construct a direct reference to a named collection.

using Microsoft.Data.Sqlite;
using Microsoft.SemanticKernel.Connectors.Sqlite;

var connection = new SqliteConnection("Data Source=:memory:");

connection.LoadExtension("vector-search-extension-name");

var collection = new SqliteVectorStoreRecordCollection<Hotel>(connection, "skhotels");

Data mapping

The SQLite Vector Store connector provides a default mapper when mapping from the data model to storage. This mapper does a direct conversion of the list of properties on the data model to the columns in SQLite.

It's also possible to override the default mapper behavior by providing a custom mapper via the SqliteVectorStoreRecordCollectionOptions<TRecord>.DictionaryCustomMapper property.

With the vector search extension, vectors are stored in virtual tables, separately from key and data properties. By default, the virtual table with vectors will use the same name as the table with key and data properties, but with a vec_ prefix. For example, if the collection name in SqliteVectorStoreRecordCollection is skhotels, the name of the virtual table with vectors will be vec_skhotels. It's possible to override the virtual table name by using the SqliteVectorStoreOptions.VectorVirtualTableName or SqliteVectorStoreRecordCollectionOptions<TRecord>.VectorVirtualTableName properties.

Property name override

You can override property names to use in storage that is different to the property names on the data model. The property name override is done by setting the StoragePropertyName option via the data model property attributes or record definition.

Here is an example of a data model with StoragePropertyName set on its attributes and how that will be represented in SQLite query.

using Microsoft.Extensions.VectorData;

public class Hotel
{
    [VectorStoreRecordKey]
    public ulong HotelId { get; set; }

    [VectorStoreRecordData(StoragePropertyName = "hotel_name")]
    public string? HotelName { get; set; }

    [VectorStoreRecordData(StoragePropertyName = "hotel_description")]
    public string? Description { get; set; }

    [VectorStoreRecordVector(Dimensions: 4, DistanceFunction.CosineDistance)]
    public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }
}

CREATE TABLE Hotels (
    HotelId INTEGER PRIMARY KEY,
    hotel_name TEXT,
    hotel_description TEXT
);

CREATE VIRTUAL TABLE vec_Hotels (
    HotelId INTEGER PRIMARY KEY,
    DescriptionEmbedding FLOAT[4] distance_metric=cosine
);

Coming soon

More info coming soon.

Coming soon

More info coming soon.