mhayes853/sqlite-vec-data

Overview

SQLiteVecData bridges SQLiteData and sqlite-vec so you can create vec0 tables and run vector queries in pure Swift.

Quick Start

Call loadSQLiteVecExtension in your database preparation so every connection can use vec0 tables and vector functions.

import SQLiteVecData

extension DependencyValues {
  mutating func bootstrapDatabase() throws {
    var configuration = Configuration()
    configuration.prepareDatabase = { db in
      try db.loadSQLiteVecExtension()
    }
    let database = try SQLiteData.defaultDatabase(configuration: configuration)
    var migrator = DatabaseMigrator()
    try migrator.migrate(database)
    defaultDatabase = database
  }
}

@main
struct MyApp: App {
  init() {
    prepareDependencies {
      try! $0.bootstrapDatabase()
    }
  }
}

Create a vec0 table

First, create the vec0 virtual table in your migration.

CREATE VIRTUAL TABLE "Embeddings" USING vec0(
  embedding FLOAT[1536],
  label TEXT
);

Then model the table in Swift by conforming to Vec0 and using a vector bytes representation.

@Table("Embeddings")
struct Embedding: Vec0 {
  @Column(as: [Float].VectorBytesRepresentation.self)
  var embedding: [Float]

  var label: String
}

Match queries

Use match to filter rows by vector similarity, and order by the vec0 distance column for nearest neighbors.

let queryVector: [Float].VectorBytesRepresentation = [0.1, 0.2, 0.3]
let query = Embedding
  .where { $0.embedding.match(queryVector) }
  .order { $0.distance.asc() }
  .limit(5)
  .select { ($0.label, $0.distance) }

Distance functions

You can also compute distances directly in select clauses.

let queryVector: [Float].VectorBytesRepresentation = [0.1, 0.2, 0.3]
let query = Embedding.select {
  ($0.label, $0.embedding.distanceCosine(to: queryVector))
}

EmbeddingVector

EmbeddingVector is a Hashable and Codable fixed-length array alternative to InlineArray. It is available on iOS 26.0, macOS 26.0, tvOS 26.0, watchOS 26.0, and visionOS 26.0, and it can be stored in vec0 tables or used directly as a query binding.

@Table("Embeddings")
struct Embedding: Vec0 {
  var id: UUID
  var embedding: EmbeddingVector<1536>
}

let queryVector = EmbeddingVector<1536>([...])
let query = Embedding
  .where { $0.embedding.match(queryVector) }
  .select { ($0.id, $0.distance) }

Targets

SQLiteVecData is the main integration target that couples SQLiteData with sqlite-vec. It also exports StructuredQueriesSQLiteVecCore.

StructuredQueriesSQLiteVecCore is a standalone set of query helpers that model sqlite-vec features in StructuredQueries. Use this if you don't plan to use SQLiteData directly.

Documentation

The documentation for releases and main are available here.

• SQLiteVecData (main)
• SQLiteVecData (0.x.x)
• StructuredQueriesSQLiteVecCore (main)
• StructuredQueriesSQLiteVecCore (0.x.x)

Installation

You can add SQLiteVecData to an Xcode project by adding it to your project as a package.

https://github.com/mhayes853/sqlite-vec-data

If you want to use SQLiteVecData in a SwiftPM project, add it to your Package.swift.

dependencies: [
  .package(url: "https://github.com/mhayes853/sqlite-vec-data", from: "0.1.0")
]

Then add the product to any target that needs it.

.product(name: "SQLiteVecData", package: "sqlite-vec-data")

License

This library is licensed under an MIT License. See LICENSE for details.

Package Metadata

Repository: mhayes853/sqlite-vec-data

Default branch: main

README: README.md