Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pgvector/pgvector-go
pgvector support for Go
https://github.com/pgvector/pgvector-go
Last synced: about 2 months ago
JSON representation
pgvector support for Go
- Host: GitHub
- URL: https://github.com/pgvector/pgvector-go
- Owner: pgvector
- License: mit
- Created: 2021-06-17T00:31:43.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2024-07-27T01:30:57.000Z (about 2 months ago)
- Last Synced: 2024-07-27T02:35:44.398Z (about 2 months ago)
- Language: Go
- Homepage:
- Size: 128 KB
- Stars: 153
- Watchers: 5
- Forks: 6
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
- awesome - pgvector/pgvector-go - pgvector support for Go (Go)
README
# pgvector-go
[pgvector](https://github.com/pgvector/pgvector) support for Go
Supports [pgx](https://github.com/jackc/pgx), [pg](https://github.com/go-pg/pg), [Bun](https://github.com/uptrace/bun), [Ent](https://github.com/ent/ent), [GORM](https://github.com/go-gorm/gorm), and [sqlx](https://github.com/jmoiron/sqlx)
[](https://github.com/pgvector/pgvector-go/actions)
## Getting Started
Run:
```sh
go get github.com/pgvector/pgvector-go
```
And follow the instructions for your database library:
- [pgx](#pgx)
- [pg](#pg)
- [Bun](#bun)
- [Ent](#ent)
- [GORM](#gorm)
- [sqlx](#sqlx)
Or check out some examples:
- [Embeddings](examples/openai/main.go) with OpenAI
- [Binary embeddings](examples/cohere/main.go) with Cohere
- [Recommendations](examples/disco/main.go) with Disco
- [Horizontal scaling](examples/citus/main.go) with Citus
- [Bulk loading](examples/loading/main.go) with `COPY`
## pgx
Import the packages
```go
import (
"github.com/pgvector/pgvector-go"
pgxvector "github.com/pgvector/pgvector-go/pgx"
)
```
Enable the extension
```go
_, err := conn.Exec(ctx, "CREATE EXTENSION IF NOT EXISTS vector")
```
Register the types
```go
err := pgxvector.RegisterTypes(ctx, conn)
```
Create a table
```go
_, err := conn.Exec(ctx, "CREATE TABLE items (id bigserial PRIMARY KEY, embedding vector(3))")
```
Insert a vector
```go
_, err := conn.Exec(ctx, "INSERT INTO items (embedding) VALUES ($1)", pgvector.NewVector([]float32{1, 2, 3}))
```
Get the nearest neighbors to a vector
```go
rows, err := conn.Query(ctx, "SELECT id FROM items ORDER BY embedding <-> $1 LIMIT 5", pgvector.NewVector([]float32{1, 2, 3}))
```
Add an approximate index
```go
_, err := conn.Exec(ctx, "CREATE INDEX ON items USING hnsw (embedding vector_l2_ops)")
// or
_, err := conn.Exec(ctx, "CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops) WITH (lists = 100)")
```
Use `vector_ip_ops` for inner product and `vector_cosine_ops` for cosine distance
See a [full example](pgx_test.go)
## pg
Import the package
```go
import "github.com/pgvector/pgvector-go"
```
Enable the extension
```go
_, err := db.Exec("CREATE EXTENSION IF NOT EXISTS vector")
```
Add a vector column
```go
type Item struct {
Embedding pgvector.Vector `pg:"type:vector(3)"`
}
```
Insert a vector
```go
item := Item{
Embedding: pgvector.NewVector([]float32{1, 2, 3}),
}
_, err := db.Model(&item).Insert()
```
Get the nearest neighbors to a vector
```go
var items []Item
err := db.Model(&items).
OrderExpr("embedding <-> ?", pgvector.NewVector([]float32{1, 2, 3})).
Limit(5).
Select()
```
Add an approximate index
```go
_, err := conn.Exec(ctx, "CREATE INDEX ON items USING hnsw (embedding vector_l2_ops)")
// or
_, err := conn.Exec(ctx, "CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops) WITH (lists = 100)")
```
Use `vector_ip_ops` for inner product and `vector_cosine_ops` for cosine distance
See a [full example](pg_test.go)
## Bun
Import the package
```go
import "github.com/pgvector/pgvector-go"
```
Enable the extension
```go
_, err := db.Exec("CREATE EXTENSION IF NOT EXISTS vector")
```
Add a vector column
```go
type Item struct {
Embedding pgvector.Vector `bun:"type:vector(3)"`
}
```
Insert a vector
```go
item := Item{
Embedding: pgvector.NewVector([]float32{1, 2, 3}),
}
_, err := db.NewInsert().Model(&item).Exec(ctx)
```
Get the nearest neighbors to a vector
```go
var items []Item
err := db.NewSelect().
Model(&items).
OrderExpr("embedding <-> ?", pgvector.NewVector([]float32{1, 2, 3})).
Limit(5).
Scan(ctx)
```
Add an approximate index
```go
var _ bun.AfterCreateTableHook = (*Item)(nil)
func (*Item) AfterCreateTable(ctx context.Context, query *bun.CreateTableQuery) error {
_, err := query.DB().NewCreateIndex().
Model((*Item)(nil)).
Index("items_embedding_idx").
ColumnExpr("embedding vector_l2_ops").
Using("hnsw").
Exec(ctx)
return err
}
```
Use `vector_ip_ops` for inner product and `vector_cosine_ops` for cosine distance
See a [full example](bun_test.go)
## Ent
Import the package
```go
import "github.com/pgvector/pgvector-go"
```
Enable the extension (requires the [sql/execquery](https://entgo.io/docs/feature-flags/#sql-raw-api) feature)
```go
_, err := client.ExecContext(ctx, "CREATE EXTENSION IF NOT EXISTS vector")
```
Add a vector column
```go
func (Item) Fields() []ent.Field {
return []ent.Field{
field.Other("embedding", pgvector.Vector{}).
SchemaType(map[string]string{
dialect.Postgres: "vector(3)",
}),
}
}
```
Insert a vector
```go
_, err := client.Item.
Create().
SetEmbedding(pgvector.NewVector([]float32{1, 2, 3})).
Save(ctx)
```
Get the nearest neighbors to a vector
```go
items, err := client.Item.
Query().
Order(func(s *sql.Selector) {
s.OrderExpr(sql.ExprP("embedding <-> $1", pgvector.NewVector([]float32{1, 2, 3})))
}).
Limit(5).
All(ctx)
```
Add an approximate index
```go
func (Item) Indexes() []ent.Index {
return []ent.Index{
index.Fields("embedding").
Annotations(
entsql.IndexType("hnsw"),
entsql.OpClass("vector_l2_ops"),
),
}
}
```
Use `vector_ip_ops` for inner product and `vector_cosine_ops` for cosine distance
See a [full example](ent_test.go)
## GORM
Import the package
```go
import "github.com/pgvector/pgvector-go"
```
Enable the extension
```go
db.Exec("CREATE EXTENSION IF NOT EXISTS vector")
```
Add a vector column
```go
type Item struct {
Embedding pgvector.Vector `gorm:"type:vector(3)"`
}
```
Insert a vector
```go
item := Item{
Embedding: pgvector.NewVector([]float32{1, 2, 3}),
}
result := db.Create(&item)
```
Get the nearest neighbors to a vector
```go
var items []Item
db.Clauses(clause.OrderBy{
Expression: clause.Expr{SQL: "embedding <-> ?", Vars: []interface{}{pgvector.NewVector([]float32{1, 1, 1})}},
}).Limit(5).Find(&items)
```
Add an approximate index
```go
db.Exec("CREATE INDEX ON items USING hnsw (embedding vector_l2_ops)")
// or
db.Exec("CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops) WITH (lists = 100)")
```
Use `vector_ip_ops` for inner product and `vector_cosine_ops` for cosine distance
See a [full example](gorm_test.go)
## sqlx
Import the package
```go
import "github.com/pgvector/pgvector-go"
```
Enable the extension
```go
db.MustExec("CREATE EXTENSION IF NOT EXISTS vector")
```
Add a vector column
```go
type Item struct {
Embedding pgvector.Vector
}
```
Insert a vector
```go
item := Item{
Embedding: pgvector.NewVector([]float32{1, 2, 3}),
}
_, err := db.NamedExec(`INSERT INTO items (embedding) VALUES (:embedding)`, item)
```
Get the nearest neighbors to a vector
```go
var items []Item
db.Select(&items, "SELECT * FROM items ORDER BY embedding <-> $1 LIMIT 5", pgvector.NewVector([]float32{1, 1, 1}))
```
Add an approximate index
```go
db.MustExec("CREATE INDEX ON items USING hnsw (embedding vector_l2_ops)")
// or
db.MustExec("CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops) WITH (lists = 100)")
```
Use `vector_ip_ops` for inner product and `vector_cosine_ops` for cosine distance
See a [full example](sqlx_test.go)
## History
View the [changelog](https://github.com/pgvector/pgvector-go/blob/master/CHANGELOG.md)
## Contributing
Everyone is encouraged to help improve this project. Here are a few ways you can help:
- [Report bugs](https://github.com/pgvector/pgvector-go/issues)
- Fix bugs and [submit pull requests](https://github.com/pgvector/pgvector-go/pulls)
- Write, clarify, or fix documentation
- Suggest or add new features
To get started with development:
```sh
git clone https://github.com/pgvector/pgvector-go.git
cd pgvector-go
go mod tidy
createdb pgvector_go_test
go generate ./ent
go test -v
```
To run an example:
```sh
go run ./examples/loading
```