apunkt/sqlite-vec
1
0
Fork 0
mirror of https://github.com/asg017/sqlite-vec.git synced 2026-04-26 01:06:27 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

doc updates

Browse source
This commit is contained in:
Alex Garcia 2024-06-22 16:46:33 -07:00
parent df48ac2416
commit b62f6f19a8
31 changed files with 751 additions and 97 deletions
Download patch file Download diff file Expand all files Collapse all files

93
site/.vitepress/config.mts
View file

@ -11,6 +11,17 @@ const VERSION = readFileSync(
"utf8"
);
const sqliteLanuage = JSON.parse(
readFileSync(
join(
dirname(fileURLToPath(import.meta.url)),
"..",
"sqlite.tmlanguage.json"
),
"utf8"
)
);
function head(): HeadConfig[] {
return [
[
@ -18,7 +29,7 @@ function head(): HeadConfig[] {
{
rel: "shortcut icon",
type: "image/svg+xml",
href: "favicon.svg",
href: "./logo.light.svg",
},
],
[
@ -36,22 +47,34 @@ const guides = {
text: "Guides",
collapsed: true,
items: [
{ text: "Binary Quantization", link: "/guides/binary-quant" },
{ text: "Scalar Quantization", link: "/guides/scalar-quant" },
{ text: "Performance", link: "/guides/performance" },
{
text: "Matryosha/Adaptive Length Embeddings",
link: "/guides/matryoshka",
text: "Vector operations",
items: [
{ text: "Vector Arithmetic", link: "/guides/arithmetic" },
{ text: "Binary Quantization", link: "/guides/binary-quant" },
{ text: "Scalar Quantization", link: "/guides/scalar-quant" },
{
text: "Matryoshka Embeddings",
link: "/guides/matryoshka",
},
],
},
{
text: "Build with sqlite-vec",
items: [
{ text: "Semantic Search", link: "/guides/semantic-search" },
{ text: "Hybrid Search", link: "/guides/hybrid-search" },
{ text: "Retrival Augmented Generation (RAG)", link: "/guides/rag" },
{ text: "Classifiers", link: "/guides/classifiers" },
],
},
{ text: "Semantic Search", link: "/guides/semantic-search" },
{ text: "Hybrid Search", link: "/guides/hybrid-search" },
{ text: "Classifiers", link: "/guides/classifiers" },
{ text: "Improving Performance", link: "/guides/improving-perf" },
],
};
function nav(): DefaultTheme.NavItem[] {
return [
guides,
{ text: "API Reference", link: "/api-reference" },
{ text: "♥ Sponsor", link: "https://github.com/sponsors/asg017" },
{
@ -103,17 +126,25 @@ function sidebar(): DefaultTheme.SidebarItem[] {
return [
{
text: "Getting Started",
collapsed: false,
collapsed: true,
items: [
{
text: "Quickstart",
link: "/getting-started",
text: "Installation",
link: "/installation",
},
{
text: "Introduction",
link: "/introduction",
},
{
text: "Quick Start",
link: "/quickstart",
},
],
},
{
text: "Using with...",
collapsed: false,
collapsed: true,
items: [
{ text: "Python", link: "/python" },
{ text: "JavaScript", link: "/js" },
@ -124,7 +155,6 @@ function sidebar(): DefaultTheme.SidebarItem[] {
{ text: "WebAssembly (Browser)", link: "/wasm" },
{ text: "Datasette", link: "/datasette" },
{ text: "sqlite-utils", link: "/sqlite-utils" },
{ text: "Loadable Extension", link: "/loadable" },
],
},
guides,
@ -135,6 +165,10 @@ function sidebar(): DefaultTheme.SidebarItem[] {
{ text: "API Reference", link: "/api-reference" },
],
},
{
text: "Sponsors",
link: "/sponsors",
},
{
text: "See also",
items: [
@ -163,13 +197,18 @@ export default defineConfig({
head: head(),
base: "/sqlite-vec/",
themeConfig: {
logo: {
light: "/logo.dark.svg",
dark: "/logo.light.svg",
alt: "sqlite-vec logo",
},
nav: nav(),
sidebar: sidebar(),
footer: {
message: "MIT License",
copyright: "Copyright © 2024 Alex Garcia",
message: "MIT/Apache-2 License",
copyright:
'Copyright © 2024 <a href="https://alexgarcia.xyz/">Alex Garcia</a>',
},
outline: "deep",
search: {
@ -185,20 +224,10 @@ export default defineConfig({
},
rewrites: {
"using/:pkg.md": ":pkg.md",
"guides/:pkg.md": ":pkg.md",
"getting-started/:pkg.md": ":pkg.md",
//"guides/:pkg.md": ":pkg.md",
},
markdown: {
languages: [
JSON.parse(
readFileSync(
join(
dirname(fileURLToPath(import.meta.url)),
"..",
"sqlite.tmlanguage.json"
),
"utf8"
)
),
],
languages: [sqliteLanuage],
},
});

38
site/.vitepress/theme/HeroImg.vue Normal file
View file

@ -0,0 +1,38 @@
<script setup lang="ts"></script>
<template>
<div
style="
background: var(--vp-c-default-3);
padding: -4px 12px;
border-radius: 10px;
"
>
<div>
<div class="language-sqlite vp-adaptive-theme">
<pre
class="shiki shiki-themes github-light github-dark vp-code"
><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">-- store 768-dimensional vectors in a vec0 virtual table</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">create</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> virtual</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> table</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> vec_movies </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">using</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> vec0(</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> synopsis_embedding </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">float</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[768]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">-- insert vectors into the table, as JSON or compact BLOBs</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">insert into</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> vec_movies(rowid, synopsis_embedding)</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> select</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> rowid,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> embed(synopsis) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">as</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> synopsis_embedding</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> from</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> movies;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">-- KNN search!</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">select</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> rowid,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> distance</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> vec_movies</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">where</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> synopsis_embedding </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">match</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> embed(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'scary futuristic movies'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">order by</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> distance</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">limit</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 20</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span></code></pre>
</div>
</div>
</div>
</template>

32
site/.vitepress/theme/Sponsors.vue
View file

@ -11,7 +11,7 @@ const sponsors = computed(() => {
{
name: "Mozilla Builders",
url: "",
img: withBase("./mozilla.svg"),
img: withBase("/mozilla.svg"),
},
],
},
@ -21,7 +21,7 @@ const sponsors = computed(() => {
{
name: "Fly.io",
url: "https://fly.io",
img: withBase("./flyio.svg"),
img: withBase("/flyio.svg"),
},
],
},
@ -31,7 +31,7 @@ const sponsors = computed(() => {
{
name: "Turso",
url: "https://turso.tech",
img: withBase("./turso.svg"),
img: withBase("/turso.svg"),
},
],
},
@ -41,7 +41,7 @@ const sponsors = computed(() => {
{
name: "SQLite Cloud",
url: "https://sqlitecloud.io",
img: withBase("./sqlitecloud.svg"),
img: withBase("/sqlitecloud.svg"),
},
],
},
@ -51,18 +51,20 @@ const sponsors = computed(() => {
<template>
<!--<a class="sponsors-aside-text" href="/sponsor/">Sponsors</a>-->
<VPDocAsideSponsors :data="sponsors" />
<div
style="
font-size: 14px;
text-align: center;
font-style: italic;
margin-top: 4px;
"
>
<a href="https://github.com/asg017/sqlite-vec#sponsors"
>Become a sponsor! ↗</a
<div>
<VPDocAsideSponsors :data="sponsors" />
<div
style="
font-size: 14px;
text-align: center;
font-style: italic;
margin-top: 4px;
"
>
<a href="https://github.com/asg017/sqlite-vec#sponsors"
>Become a sponsor! ↗</a
>
</div>
</div>
</template>

3
site/.vitepress/theme/index.ts
View file

@ -4,6 +4,7 @@ import type { Theme } from "vitepress";
import DefaultTheme from "vitepress/theme";
import "./style.css";
import Sponsors from "./Sponsors.vue";
import HeroImg from "./HeroImg.vue";
export default {
extends: DefaultTheme,
@ -14,7 +15,7 @@ export default {
h("marquee", { class: "banner", scrollamount: "10" }, [
"🚧🚧🚧 sqlite-vec is still in beta, and this documentation is incomplete! Watch the repo for updates 🚧🚧🚧",
]),
"home-hero-image": () => h("div", {}, [""]),
//"home-hero-image": () => h(HeroImg),
"aside-ads-before": () => h(Sponsors),
});
},

42
site/.vitepress/theme/style.css
View file

@ -1,3 +1,21 @@
/*@import "https://code.cdn.mozilla.net/fonts/zilla-slab.css";*/
@font-face {
font-family: "ZillaSlab-SemiBold";
src: url("/fonts/ZillaSlab-SemiBold.woff");
src: url("/fonts/ZillaSlab-SemiBold.woff2") format("woff2"),
url("/fonts/ZillaSlab-SemiBold.woff") format("woff"),
url("/fonts/ZillaSlab(-SemiBold).otf") format("opentype"),
url("/fonts/ZillaSlab-SemiBold.ttf") format("truetype");
font-weight: 600;
font-style: normal;
}
.VPHero h1,
.VPNavBarTitle .title {
font-family: "ZillaSlab-SemiBold";
font-size: 1.5rem;
}
/**
* Customize default theme styling by overriding CSS variables:
* https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css
@ -68,6 +86,17 @@
--vp-c-danger-2: var(--vp-c-red-2);
--vp-c-danger-3: var(--vp-c-red-3);
--vp-c-danger-soft: var(--vp-c-red-soft);
--vp-c-brand-1x: #a6d189;
--vp-c-brand-1x: #a6da95;
--vp-c-brand-1x: #a6e3a1;
}
:root {
--vp-c-brand-1: #1e66f5;
}
.dark {
--vp-c-brand-1: #89b4fa;
}
/**
@ -92,19 +121,20 @@
:root {
--vp-home-hero-name-color: transparent;
--vp-home-hero-name-background: -webkit-linear-gradient(
120deg,
#f5c2e7 30%,
#94e2d5 /*#bd34fe 30%,
#41d1ff*/
);
--vp-home-hero-name-background: black;
/*
--vp-home-hero-image-background-image: linear-gradient(
-45deg,
#bd34fe 50%,
#47caff 50%
);
--vp-home-hero-image-filter: blur(44px);
*/
}
.dark {
--vp-home-hero-name-background: white;
}
@media (min-width: 640px) {

49
site/getting-started/installation.md Normal file
View file

@ -0,0 +1,49 @@
# Installing
You have several options to include `sqlite-vec` into your projects, including
PyPi packages for Python, NPM packages for Node.js, Gems for Ruby, and more.
## With popular package managers
::: code-group
```bash [Python]
pip install sqlite-vec
```
```bash [Node.js]
npm install sqlite-vec
```
```bash [Bun]
bun install sqlite-vec
```
```bash [Deno]
deno add npm:sqlite-vec
```
```bash [Ruby]
gem install sqlite-vec
```
```bash [Rust]
cargo add sqlite-vec
```
```bash [Go]
go get -u github.com/asg017/sqlite-vec/bindings/go/cgo
```
```bash [Datasette]
datasette install datasette-sqlite-vec
```
```bash [sqlite-utils]
sqlite-utils install sqlite-utils-sqlite-vec
```
:::
Alternatively, you can download pre-compiled loadable extensions from the
[`sqlite-vec` Github Releases](https://github.com/asg017/sqlite-vec/releases/latest).

7
site/getting-started/introduction.md Normal file
View file

@ -0,0 +1,7 @@
# Introduction to `sqlite-vec`
## Intro to Vector Databases
## Vector Search in SQLite with `sqlite-vec`
## Getting help

0
site/getting-started.md → site/getting-started/quickstart.md
View file

5
site/guides/arithmetic.md Normal file
View file

@ -0,0 +1,5 @@
# Vector Arithmetic
- `vec_add()`
- `vec_sub()`
- `vec_mean()`

120
site/guides/binary-quant.md Normal file
View file

@ -0,0 +1,120 @@
# Binary Quantization
"Quantization" refers to a variety of methods and techniques for reducing the
size of vectors in a vector index. **Binary quantization** (BQ) refers to a
specific technique where each individual floating point element in a vector is
reduced to a single bit, typically by assigning `0` to negative numbers and `1`
to positive numbers.
For example, in this 8-dimensional `float32` vector:
```json
[-0.73, -0.80, 0.12, -0.73, 0.79, -0.11, 0.23, 0.97]
```
Applying binary quantization would result in the following `bit` vector:
```json
[0, 0, 1, 0, 1, 0, 1, 1]
```
The original 8-dimensional `float32` vector requires `8 * 4 = 32` bytes of space
to store. For 1 million vectors, that would be `32MB`. On the other hand, the
binary quantized 8-dimensional vector can be stored in a single byte — one bit
per element. For 1 million vectors, that would be just `1MB`, a 32x reduction!
Though keep in mind, you're bound to lose a lot quality when reducing 32 bits of
information to 1 bit. [Over-sampling and re-scoring](#re-scoring) will help a
lot.
The main goal of BQ is to dramatically reduce the size of your vector index,
resulting in faster searches and less resources. This is especially useful in
`sqlite-vec`, which is (currently) brute-force only and meant to run on small
devices. BQ is an easy low-cost method to make larger vector datasets easy to
manage.
## Binary Quantization `sqlite-vec`
The `sqlite-vec` extension offers a `vec_quantize_binary()` SQL scalar function,
which applies binary quanitization to a `float32` or `int8` vector. For every
element in a given vector, it will apply `0` to negative values and `1` to
positive values, and pack them into a `BLOB`.
```sqlite
select vec_quantize_binary('[-0.73, -0.80, 0.12, -0.73, 0.79, -0.11, 0.23, 0.97]');
-- X'd4`
```
The single byte `0xd4` in hexadecimal is `11010100` in binary.
<!-- TODO what https://github.com/asg017/sqlite-vec/issues/23 -->
## Demo
```sqlite
create virtual table vec_movies using vec0(
synopsis_embedding bit[768]
);
```
```sqlite
insert into vec_movies(rowid, synopsis_embedding)
VALUES (:id, vec_quantize_binary(:vector));
```
```sqlite
select
rowid,
distance
from vec_movies
where synopsis_embedding match vec_quantize_binary(:query)
order by distance
limit 20;
```
### Re-scoring
```sqlite
create virtual table vec_movies using vec0(
synopsis_embedding float[768],
synopsis_embedding_coarse bit[768]
);
```
```sqlite
insert into vec_movies(rowid, synopsis_embedding, synopsis_embedding_coarse)
VALUES (:id, :vector, vec_quantize_binary(:vector));
```
```sqlite
with coarse_matches as (
select
rowid,
synopsis_embedding
from vec_movies
where synopsis_embedding_coarse match vec_quantize_binary(:query)
order by distance
limit 20 * 8
),
select
rowid,
vec_distance_L2(synopsis_embedding, :query)
from coarse_matches
order by 2
limit 20;
```
# Benchmarks
## Model support
Certain embedding models, like [Nomic](https://nomic.ai/)'s
[`nomic-embed-text-v1.5`](https://huggingface.co/nomic-ai/nomic-embed-text-v1.5)
text embedding model and
[mixedbread.ai](https://www.mixedbread.ai/blog/mxbai-embed-2d-large-v1)'s
[`mxbai-embed-large-v1`](https://huggingface.co/mixedbread-ai/mxbai-embed-large-v1)
are specifically trained to perform well after binary quantization.
Other embeddings models may not, but you can still try BQ and see if it works
for your datasets. Chances are, if your vectors are normalized (ie between
`-1.0` and `1.0`) there's a good chance you will see acceptable results with BQ.

0
site/using/loadable.md → site/guides/classifiers.md
View file

0
site/guides/hybrid-search.md Normal file
View file

49
site/guides/matryoshka.md Normal file
View file

@ -0,0 +1,49 @@
# Matryoshka (Adaptive-Length) Embeddings
Matryoshka embeddings are a new class of embedding models introduced in the
TODO-YYY paper [_TODO title_](https://arxiv.org/abs/2205.13147). They allow one
to truncate excess dimensions in large vector, without lossing much quality.
Let's say your embedding model generate 1024-dimensional vectors. If you have 1
million of these 1024-dimensional vectors, they would take up `4.096 GB` of
space! You're not able to reduce the dimensions without lossing a lot of
quality - if you were to remove half of the dimensions 512-dimensional vectors,
you could expect to also lose 50% or more of the quality of results. There are
other dimensional-reduction techniques, like [PCA](#TODO), but this requires a
complicated and expensive training process.
Matryoshka embeddings, on the other hand, _can_ be truncated, without losing
quality. Using [`mixedbread.ai`](#TODO) `mxbai-embed-large-v1` model, they claim
that
They are called "Matryoshka" embeddings because ... TODO
## Matryoshka Embeddings with `sqlite-vec`
You can use a combination of [`vec_slice()`](/api-reference#vec_slice) and
[`vec_normalize()`](/api-reference#vec_slice) on Matryoshka embeddings to
truncate.
```sql
select
vec_normalize(vec_slice(title_embeddings, 0, 256)) as title_embeddings_256d
from vec_articles;
```
## Benchmarks
## Suppported Models
https://supabase.com/blog/matryoshka-embeddings#which-granularities-were-openais-text-embedding-3-models-trained-on
`text-embedding-3-small`: 1536, 512 `text-embedding-3-large`: 3072, 1024, 256
https://x.com/ZainHasan6/status/1757519325202686255
`text-embeddings-3-large:` 3072, 1536, 1024, 512
https://www.mixedbread.ai/blog/binary-mrl
`mxbai-embed-large-v1`: 1024, 512, 256, 128, 64
`nomic-embed-text-v1.5`: 768, 512, 256, 128, 64

4
site/guides/performance.md Normal file
View file

@ -0,0 +1,4 @@
- page_size
- memory mapping
- in-memory index
- chunk_size (?)

4
site/guides/rag.md Normal file
View file

@ -0,0 +1,4 @@
# Retrival Augmented Generation (RAG)
- "memories"?
- chunking

27
site/guides/scalar-quant.md Normal file
View file

@ -0,0 +1,27 @@
# Scalar Quantization (SQ)
"Quantization" refers to a variety of methods and techniques for reducing the
size of vectors in a vector index. **Scalar quantization** (SQ) refers to a
specific technique where each individual floating point element in a vector is
scaled to a small element type, like `float16`, `int8`.
Most embedding models generate `float32` vectors. Each `float32` takes up 4
bytes of space. This can add up, especially when working with a large amount of
vectors or vectors with many dimensions. However, if you scale them to `float16`
or `int8` vectors, they only take up 2 bytes of space and 1 bytes of space
respectively, saving you precious space at the expense of some quality.
```sql
select vec_quantize_float16(vec_f32('[]'), 'unit');
select vec_quantize_int8(vec_f32('[]'), 'unit');
select vec_quantize('float16', vec_f32('...'));
select vec_quantize('int8', vec_f32('...'));
select vec_quantize('bit', vec_f32('...'));
select vec_quantize('sqf16', vec_f32('...'));
select vec_quantize('sqi8', vec_f32('...'));
select vec_quantize('bq2', vec_f32('...'));
```
## Benchmarks

0
site/guides/semantic-search.md Normal file
View file

41
site/index.md
View file

@ -9,14 +9,14 @@ hero:
actions:
- theme: brand
text: Getting Started
link: /getting-started
link: /introduction
- theme: alt
text: API Reference
link: /api-reference
features:
- title: Runs everywhere
details: On the server, in the browser with WASM, mobile devices, and more!
details: On laptops, servers, mobile devices, browsers with WASM, Raspberry Pis, and more!
- title: Bindings for many languages
details: Python, Ruby, Node.js/Deno/Bun, Go, Rust, and more!
- title: Only SQL
@ -24,49 +24,24 @@ features:
---
```sqlite
-- store 768-dimensional vectors in a vec0 virtual table
create virtual table vec_movies using vec0(
synopsis_embedding float[768]
);
-- insert vectors into the table, as JSON or compact BLOBs
insert into vec_movies(rowid, synopsis_embedding)
select
rowid,
embed(synopsis) as synopsis_embedding
from movies;
select rowid, distance
-- KNN search!
select
rowid,
distance
from vec_movies
where synopsis_embedding match embed('scary futuristic movies')
order by distance
limit 20;
```
---
<div class="language-sqlite vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">sqlite</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">create</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> virtual</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> table</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> vec_movies </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">using</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> vec0(</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> synopsis_embedding </span><span id="xxx"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">float</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[768]</span></span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">insert into</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> vec_movies(rowid, synopsis_embedding)</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> select</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> rowid,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> embed(synopsis) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">as</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> synopsis_embedding</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> from</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> movies;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">select</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> rowid, distance</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> vec_movies</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">where</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> synopsis_embedding </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">match</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> embed(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'scary futuristic movies'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">order by</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> distance</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">limit</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 20</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span></code></pre></div>
<script>
//document.querySelector('#xxx').style.background = 'red'
</script>
<script setup>
import { onMounted } from 'vue'
onMounted(() => {
document.querySelector('#xxx').style.background = 'red';
});
</script>

2
site/project.data.ts
View file

@ -1,9 +1,9 @@
import { defineConfig } from "vitepress";
import { readFileSync } from "node:fs";
import { join, dirname } from "node:path";
import { fileURLToPath } from "node:url";
const PROJECT = "sqlite-vec";
const VERSION = readFileSync(
join(dirname(fileURLToPath(import.meta.url)), "..", "VERSION"),
"utf8"

BIN
site/public/fonts/ZillaSlab-SemiBold.otf Normal file
View file

Binary file not shown.

BIN
site/public/fonts/ZillaSlab-SemiBold.ttf Normal file
View file

Binary file not shown.

BIN
site/public/fonts/ZillaSlab-SemiBold.woff Normal file
View file

Binary file not shown.

BIN
site/public/fonts/ZillaSlab-SemiBold.woff2 Normal file
View file

Binary file not shown.

17
site/public/logo.dark.svg Normal file
View file

@ -0,0 +1,17 @@
<svg width="256" height="256" viewBox="0 0 256 256" fill="none" xmlns="http://www.w3.org/2000/svg">
<rect width="256" height="256" fill="#1E1E2E" rx="30"/>
<rect x="60.0452" y="174" width="132.873" height="41.2651" fill="#CDD6F4"/>
<path d="M80.2651 194.633C80.2651 206.028 71.0276 215.265 59.6325 215.265C48.2375 215.265 39 206.028 39 194.633C39 183.237 48.2375 174 59.6325 174C71.0276 174 80.2651 183.237 80.2651 194.633Z" fill="#CDD6F4"/>
<path d="M214.789 194.633C214.789 206.028 205.552 215.265 194.157 215.265C182.762 215.265 173.524 206.028 173.524 194.633C173.524 183.237 182.762 174 194.157 174C205.552 174 214.789 183.237 214.789 194.633Z" fill="#CDD6F4"/>
<rect x="61.0452" y="107.867" width="45.3916" height="41.2651" fill="#89DCEB"/>
<rect x="151.828" y="107.867" width="45.3916" height="41.2651" fill="#89DCEB"/>
<circle cx="61.0452" cy="128.5" r="20.6325" fill="#89DCEB"/>
<circle cx="61.0452" cy="128.5" r="20.6325" fill="#89DCEB"/>
<circle cx="105.611" cy="128.5" r="20.6325" fill="#89DCEB"/>
<circle cx="150.178" cy="128.5" r="20.6325" fill="#89DCEB"/>
<circle cx="194.744" cy="128.5" r="20.6325" fill="#89DCEB"/>
<circle cx="61.0452" cy="62.6325" r="20.6325" fill="#CBA6F7"/>
<circle cx="105.611" cy="62.6325" r="20.6325" fill="#CBA6F7"/>
<circle cx="150.178" cy="62.6325" r="20.6325" fill="#CBA6F7"/>
<circle cx="194.744" cy="62.6325" r="20.6325" fill="#CBA6F7"/>
</svg>
Side by side

After

Width:  |  Height:  |  Size: 1.4 KiB

17
site/public/logo.light.svg Normal file
View file

@ -0,0 +1,17 @@
<svg width="256" height="256" viewBox="0 0 256 256" fill="none" xmlns="http://www.w3.org/2000/svg">
<rect width="256" height="256" fill="#EFF1F5" rx="30"/>
<rect x="60.0452" y="174" width="132.873" height="41.2651" fill="#4C4F69"/>
<path d="M80.2651 194.633C80.2651 206.028 71.0276 215.265 59.6325 215.265C48.2375 215.265 39 206.028 39 194.633C39 183.237 48.2375 174 59.6325 174C71.0276 174 80.2651 183.237 80.2651 194.633Z" fill="#4C4F69"/>
<path d="M214.789 194.633C214.789 206.028 205.552 215.265 194.157 215.265C182.762 215.265 173.524 206.028 173.524 194.633C173.524 183.237 182.762 174 194.157 174C205.552 174 214.789 183.237 214.789 194.633Z" fill="#4C4F69"/>
<rect x="61.0452" y="107.867" width="45.3916" height="41.2651" fill="#04A5E5"/>
<rect x="151.828" y="107.867" width="45.3916" height="41.2651" fill="#04A5E5"/>
<circle cx="61.0452" cy="128.5" r="20.6325" fill="#04A5E5"/>
<circle cx="61.0452" cy="128.5" r="20.6325" fill="#04A5E5"/>
<circle cx="105.611" cy="128.5" r="20.6325" fill="#04A5E5"/>
<circle cx="150.178" cy="128.5" r="20.6325" fill="#04A5E5"/>
<circle cx="194.744" cy="128.5" r="20.6325" fill="#04A5E5"/>
<circle cx="61.0452" cy="62.6325" r="20.6325" fill="#8839EF"/>
<circle cx="105.611" cy="62.6325" r="20.6325" fill="#8839EF"/>
<circle cx="150.178" cy="62.6325" r="20.6325" fill="#8839EF"/>
<circle cx="194.744" cy="62.6325" r="20.6325" fill="#8839EF"/>
</svg>
Side by side

After

Width:  |  Height:  |  Size: 1.4 KiB

54
site/using/js.md
View file

@ -1,13 +1,65 @@
# Using `sqlite-vec` in Node.js, Deno, and Bun
```bash
To use `sqlite-vec` in Node.js, Deno or Bun, install the
[`sqlite-vec` NPM package](https://npmjs.com/package/sqlite-vec) using your
favorite package manager:
::: code-group
```bash [npm]
npm install sqlite-vec
```
```bash [Bun]
bun install sqlite-vec
```
```bash [Deno]
deno add npm:sqlite-vec
```
:::
Once installed, use the `sqliteVec.load()` function to load `sqlite-vec` SQL
functions into a SQLite connection.
```js
import * as sqliteVec from "sqlite-vec";
import Database from "better-sqlite3";
const db = new Database(":memory:");
sqliteVec.load(db);
const { vec_version } = db
.prepare("select vec_version() as vec_version;")
.get();
console.log(`vec_version=${vec_version}`);
```
The `load()` function is compatable with
[`better-sqlite3`](https://github.com/WiseLibs/better-sqlite3),
[`node-sqlite3`](https://github.com/TryGhost/node-sqlite3),
[`js:@db/sqlite`](https://jsr.io/@db/sqlite) (Deno), and
[`bun:sqlite`](https://bun.sh/docs/api/sqlite).
## Working with vectors in JavaScript
if your vectors are represented as an array of numbers, use
[Float32Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float32Array),
use the
[`.buffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/buffer)
accessor to insert the underlying ArrayBuffer.
```js
const embedding = new Float32Array([0.1, 0.2, 0.3]);
const stmt = db.prepare("INSERT INTO vss_demo VALUES (?)");
stmt.run(embedding.buffer);
## Node.js
## Deno
## Bun
```

126
site/using/python.md
View file

@ -4,12 +4,21 @@ title: sqlite-vec in Python
# Using `sqlite-vec` in Python
[![PyPI](https://img.shields.io/pypi/v/sqlite-vec.svg?color=blue&logo=python&logoColor=white)](https://pypi.org/project/sqlite-vec/)
To use `sqlite-vec` from Python, install the
[`sqlite-vec` PyPi package](https://pypi.org/project/sqlite-vec/) using your
favorite Python package manager:
```bash
pip install sqlite-vec
```
Once installed, use the `sqlite_vec.load()` function to load `sqlite-vec` SQL
functions into a SQLite connection.
```python
import sqlite
import sqlite3
import sqlite_vec
db = sqlite3.connect(":memory:")
@ -19,13 +28,122 @@ db.enable_load_extension(False)
vec_version, = db.execute("select vec_version()").fetchone()
print(f"vec_version={vec_version}")
```
## Working with Vectors
### Vectors as Lists
### Lists
### `numpy` Arrays
If the vectors you are working with are provided as a list of floats, you can convert them into the compact BLOB format that `sqlite-vec` uses with [`struct.pack()`](https://docs.python.org/3/library/struct.html#struct.pack).
```python
import struct
def serialize(vector: List[float]) -> bytes:
""" serializes a list of floats into a compact "raw bytes" format """
return struct.pack('%sf' % len(vector), *vector)
embedding = [0.1, 0.2, 0.3, 0.4]
result = db.execute('select vec_length(?)', [serialize(embedding)]).fetchone()[0]
print(result) # 4
```
### NumPy Arrays
If your vectors are from `numpy` arrays, the Python SQLite package allows you to pass it along as-is. Make sure you convert your array elements to 32-bit floats with [`.astype(np.float32)`](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.astype.html), as some embedding services will use `np.float64` elements.
```python
import numpy as np
embedding = np.array([0.1, 0.2, 0.3, 0.4])
result = db.execute('select vec_length(?)', [embedding.astype(np.float32)]).fetchone()[0]
print(result) # 4
```
## Recipes
### OpenAI
https://platform.openai.com/docs/guides/embeddings/what-are-embeddings?lang=python
TODO
```python
from openai import OpenAI
import sqlite3
import sqlite_vec
texts = [
'Capri-Sun is a brand of juice concentrate–based drinks manufactured by the German company Wild and regional licensees.',
'Shohei Ohtani is a Japanese professional baseball pitcher and designated hitter for the Los Angeles Dodgers of Major League Baseball.',
'George V was King of the United Kingdom and the British Dominions, and Emperor of India, from 6 May 1910 until his death in 1936.',
'Alan Mathison Turing was an English mathematician, computer scientist, logician, cryptanalyst, philosopher and theoretical biologist.',
'Alaqua Cox is a Native American (Menominee) actress.'
]
# change ':memory:' to a filepath to persist data
db = sqlite3.connect(':memory:')
db.enable_load_extension(True)
sqlite_vec.load(db)
db.enable_load_extension(False)
client = OpenAI()
response = client.embeddings.create(
input=[texts],
model="text-embedding-3-small"
)
print(response.data[0].embedding)
```
### llamafile
https://github.com/Mozilla-Ocho/llamafile
TODO
### llama-cpp-python
https://github.com/abetlen/llama-cpp-python
TODO
### sentence-transformers (etc.)
https://github.com/UKPLab/sentence-transformers
TODO
## Using an up-to-date version of SQLite
Some features of `sqlite-vec` will require an up-to-date SQLite library. You can see what version of SQLite your Python environment uses with [`sqlite3.sqlite-version`](https://docs.python.org/3/library/sqlite3.html#sqlite3.sqlite_version), or with this one-line command:
```bash
python -c 'import sqlite3; print(sqlite3.sqlite_version)'
```
Currently, **SQLite version 3.41 or higher** is recommended but not required. `sqlite-vec` will work with older version, but certain features and queries will only work correctly in >=3.41.
To "upgrade" the SQLite version your Python installation uses, you have a few options.
### Compile your own SQLite version
You can compile an up-to-date version of SQLite and use some system environment variables (like `LD_PRELOAD` and `DYLD_LIBRARY_PATH`) to force Python to use a different SQLite library. [This guide](https://til.simonwillison.net/sqlite/sqlite-version-macos-python) goes into this approach in more details.
Although compiling SQLite can be straightforward, there are a lot of different compilation options to consider, which makes it confusing. This also doesn't work with Windows, which statically compiles its own SQLite library.
### Use `pysqlite3`
[`pysqlite3`](https://github.com/coleifer/pysqlite3) is a 3rd party PyPi package that bundles an up-to-date SQLite library as a separate pip package.
While it's mostly compatible with the Python `sqlite3` module, there are a few rare edge cases where the APIs don't match.
### Upgrading your Python version
Sometimes installing a latest version of Python will "magically" upgrade your SQLite version as well. This is a nuclear option, as upgrading Python installations can be quite the hassle, but most Python 3.12 builds will have a very recent SQLite version.

2
site/using/ruby.md
View file

@ -1,5 +1,7 @@
# Using `sqlite-vec` in Ruby
https://rubygems.org/gems/sqlite-vec
```bash
gem install sqlite-vec
```