{"id":44737823,"url":"https://github.com/gabisonia/go-vectorstore","last_synced_at":"2026-02-17T22:00:51.288Z","repository":{"id":337800379,"uuid":"1155251200","full_name":"gabisonia/go-vectorstore","owner":"gabisonia","description":"A lightweight Go vector-store library inspired by Microsoft.Extensions.VectorData","archived":false,"fork":false,"pushed_at":"2026-02-16T13:17:11.000Z","size":123,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-17T01:49:29.916Z","etag":null,"topics":["go-vector","postgresql","vectordb","vectorstore"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gabisonia.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-11T09:51:18.000Z","updated_at":"2026-02-16T13:15:48.000Z","dependencies_parsed_at":"2026-02-16T21:00:38.675Z","dependency_job_id":null,"html_url":"https://github.com/gabisonia/go-vectorstore","commit_stats":null,"previous_names":["gabisonia/go-vectorstore"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/gabisonia/go-vectorstore","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabisonia%2Fgo-vectorstore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabisonia%2Fgo-vectorstore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabisonia%2Fgo-vectorstore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabisonia%2Fgo-vectorstore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gabisonia","download_url":"https://codeload.github.com/gabisonia/go-vectorstore/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabisonia%2Fgo-vectorstore/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29559961,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-17T21:50:49.831Z","status":"ssl_error","status_checked_at":"2026-02-17T21:46:15.313Z","response_time":100,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go-vector","postgresql","vectordb","vectorstore"],"created_at":"2026-02-15T20:09:16.062Z","updated_at":"2026-02-17T22:00:51.252Z","avatar_url":"https://github.com/gabisonia.png","language":"Go","readme":"# go-vectorstore\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/gabisonia/go-vectorstore.svg)](https://pkg.go.dev/github.com/gabisonia/go-vectorstore)\n[![Latest Release](https://img.shields.io/github/v/release/gabisonia/go-vectorstore?sort=semver)](https://github.com/gabisonia/go-vectorstore/releases)\n[![Go Version](https://img.shields.io/github/go-mod/go-version/gabisonia/go-vectorstore)](https://github.com/gabisonia/go-vectorstore/blob/master/go.mod)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nA lightweight Go vector-store library inspired by `Microsoft.Extensions.VectorData`.\n\nMVP scope:\n- Go 1.24.x\n- Postgres + `pgvector`\n- MSSQL connector\n- Record-based core API with optional typed codec wrapper\n\nThis library can be used to build retrieval systems such as:\n- semantic search\n- RAG pipelines (retrieve from vector DB, then generate with an LLM)\n- context-aware assistants grounded on your own data\n\n## Requirements\n\n- Go 1.24.x\n- PostgreSQL 16+ with `pgvector` extension\n- SQL Server 2022+ (for `stores/mssql`)\n- Docker (optional, for integration tests and sample compose flows)\n\n## Project layout\n\n- `vectordata`: backend-agnostic core interfaces, record model, filters, typed wrapper\n- `stores/postgres`: Postgres implementation with `pgxpool`\n- `stores/mssql`: SQL Server implementation with `database/sql`\n- `samples`: runnable demos (see `samples/README.md`)\n- `docs`: architecture and implementation notes\n\n## Install\n\n```bash\ngo get github.com/gabisonia/go-vectorstore\n```\n\n## Quick Start (Local)\n\n1. Start local Postgres + `pgvector` from the repository root:\n\n```bash\ndocker compose up -d postgres\n```\n\n2. Export your OpenAI key and run the semantic sample:\n\n```bash\nexport OPENAI_API_KEY=your_key_here\ngo get github.com/gabisonia/go-vectorstore/vectordata@latest\ngo run ./samples/semantic-search -q \"how can I reduce cloud costs?\"\n```\n\n3. Stop local services when done:\n\n```bash\ndocker compose down\n```\n\n## Core API Walkthrough\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"fmt\"\n\n    \"github.com/gabisonia/go-vectorstore/stores/postgres\"\n    \"github.com/gabisonia/go-vectorstore/vectordata\"\n    \"github.com/jackc/pgx/v5/pgxpool\"\n)\n\nfunc main() {\n    ctx := context.Background()\n    pool, err := pgxpool.New(ctx, \"postgres://postgres:postgres@localhost:54329/vectorstore_test?sslmode=disable\")\n    if err != nil {\n        panic(err)\n    }\n    defer pool.Close()\n\n    store, err := postgres.NewVectorStore(pool, postgres.DefaultStoreOptions())\n    if err != nil {\n        panic(err)\n    }\n\n    collection, err := store.EnsureCollection(ctx, vectordata.CollectionSpec{\n        Name:      \"docs\",\n        Dimension: 3,\n        Metric:    vectordata.DistanceCosine,\n        Mode:      vectordata.EnsureStrict,\n    })\n    if err != nil {\n        panic(err)\n    }\n\n    records := []vectordata.Record{\n        {\n            ID:       \"doc-1\",\n            Vector:   []float32{0.1, 0.2, 0.3},\n            Metadata: map[string]any{\"category\": \"news\", \"rank\": 10},\n        },\n        {\n            ID:       \"doc-2\",\n            Vector:   []float32{0.2, 0.1, 0.2},\n            Metadata: map[string]any{\"category\": \"blog\", \"rank\": 5},\n        },\n    }\n    if err := collection.Upsert(ctx, records); err != nil {\n        panic(err)\n    }\n\n    if err := collection.EnsureIndexes(ctx, vectordata.IndexOptions{\n        Vector: \u0026vectordata.VectorIndexOptions{\n            Method: vectordata.IndexMethodHNSW,\n            Metric: vectordata.DistanceCosine,\n            HNSW: vectordata.HNSWOptions{\n                M:              16,\n                EfConstruction: 64,\n            },\n        },\n        Metadata: \u0026vectordata.MetadataIndexOptions{UsePathOps: true},\n    }); err != nil {\n        panic(err)\n    }\n\n    filter := vectordata.And(\n        vectordata.Eq(vectordata.Metadata(\"category\"), \"news\"),\n        vectordata.Gt(vectordata.Metadata(\"rank\"), 6),\n    )\n\n    results, err := collection.SearchByVector(\n        ctx,\n        []float32{0.1, 0.2, 0.25},\n        5,\n        vectordata.SearchOptions{Filter: filter},\n    )\n    if err != nil {\n        panic(err)\n    }\n\n    for _, r := range results {\n        fmt.Printf(\"id=%s score=%.4f distance=%.4f\\n\", r.Record.ID, r.Score, r.Distance)\n    }\n}\n```\n\n## Search Options\n\n`SearchByVector` supports filtering, thresholding, and projection control.\n\n```go\nthreshold := 0.35\nprojection := \u0026vectordata.Projection{\n    IncludeMetadata: true,\n    IncludeContent:  true,\n    IncludeVector:   false,\n}\n\nresults, err := collection.SearchByVector(ctx, queryVector, 10, vectordata.SearchOptions{\n    Filter:     vectordata.Eq(vectordata.Metadata(\"category\"), \"backend\"),\n    Threshold:  \u0026threshold,\n    Projection: projection,\n})\n```\n\nIf `Projection` is `nil`, the default projection includes `Metadata` and `Content`, but not `Vector`.\n\n## Store Options\n\n```go\nstore, err := postgres.NewVectorStore(pool, postgres.StoreOptions{\n    Schema:          \"public\",\n    EnsureExtension: true,\n    StrictByDefault: true,\n})\n```\n\n- `Schema`: SQL schema for collection tables\n- `EnsureExtension`: auto-runs `CREATE EXTENSION IF NOT EXISTS vector`\n- `StrictByDefault`: default ensure mode when `CollectionSpec.Mode` is not set\n\n## Integration tests\n\n```bash\ngo test -tags=integration ./...\n```\n\nUnit tests run with:\n\n```bash\ngo test ./...\n```\n\nNotes:\n- Integration tests start Postgres/pgvector and SQL Server automatically via Testcontainers\n- Docker daemon must be available when running integration tests\n- Optional override: set `PGVECTOR_TEST_DSN` to use an existing Postgres instance instead of starting a container\n- Optional override: set `MSSQL_TEST_DSN` to use an existing SQL Server instance instead of starting a container\n\nRun MSSQL integration tests against root compose service:\n\n```bash\ndocker compose up -d mssql\nMSSQL_TEST_DSN=\"sqlserver://sa:YourStrong%21Passw0rd@localhost:14339?database=master\u0026encrypt=disable\" \\\n  go test -tags=integration ./stores/mssql\n```\n\n## Docker Compose (optional)\n\n`docker-compose.yml` at the repository root is kept for manual local runs.\n\n- Use root `docker-compose.yml` when you want a persistent local Postgres+pgvector instance outside tests\n- Root compose also includes SQL Server (`mssql`) for local MSSQL connector validation\n- Use Testcontainers (`go test -tags=integration ./...`) for integration tests\n- Sample apps have their own compose files at `samples/semantic-search/docker-compose.yml` and `samples/ragrimosa/docker-compose.yml`\n- Sample Dockerfiles use `golang:1.24-alpine` to match the repo Go version (`1.24.x`)\n\n## Release Automation\n\nGitHub Actions workflows are configured for:\n\n- CI on pushes/PRs (`.github/workflows/ci.yml`)\n- release publishing (`.github/workflows/release.yml`)\n\nRelease options:\n\n1. Manual (recommended): run `Release` workflow via GitHub UI with `version` input (`0.2.2` or `v0.2.2`).\n2. Tag-driven: push a semver tag and the workflow publishes release notes automatically:\n\n```bash\ngit tag v0.2.2\ngit push origin v0.2.2\n```\n\n## Samples\n\n- Overview and entry points: [`samples/README.md`](samples/README.md)\n- Semantic search sample app: `samples/semantic-search`\n- RAG sample app (`RAGrimosa`): `samples/ragrimosa`\n\n## Documentation\n\n- Docs index: [`docs/README.md`](docs/README.md)\n- Internals and architecture: [`docs/architecture.md`](docs/architecture.md)\n\n## License\n\nThis project is licensed under the MIT License.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgabisonia%2Fgo-vectorstore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgabisonia%2Fgo-vectorstore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgabisonia%2Fgo-vectorstore/lists"}