vecna

Schema-validated filter builder for vector databases. Build type-safe metadata filters with compile-time field validation.

Filters That Know Your Schema

type DocumentMetadata struct {
    Category string   `json:"category"`
    Score    float64  `json:"score"`
    Tags     []string `json:"tags"`
}

builder, _ := vecna.New[DocumentMetadata]()

// Valid - field exists
filter := builder.Where("category").Eq("tech")

// Error - typo caught immediately
filter := builder.Where("categroy").Eq("tech")
// filter.Err() returns: vecna: field not found: categroy

Install

go get github.com/zoobz-io/vecna

Requires Go 1.24 or higher.

Quick Start

package main

import (
    "fmt"
    "github.com/zoobz-io/vecna"
)

type Metadata struct {
    Category string   `json:"category"`
    Score    float64  `json:"score"`
    Active   bool     `json:"active"`
    Tags     []string `json:"tags"`
}

func main() {
    // Create a schema-validated builder
    builder, err := vecna.New[Metadata]()
    if err != nil {
        panic(err)
    }

    // Build filters with validation
    filter := builder.And(
        builder.Where("category").Eq("tech"),
        builder.Or(
            builder.Where("score").Gte(0.8),
            builder.Where("active").Eq(true),
        ),
    )

    // Check for construction errors
    if err := filter.Err(); err != nil {
        panic(err)
    }

    // Use filter with your vector database provider
    fmt.Printf("Filter: %s %s %v\n", filter.Op(), filter.Field(), filter.Value())
}

Capabilities

Feature	Description	Docs
Schema Validation	Field names validated against your struct at build time	Concepts
Type Checking	Comparison operators blocked on non-numeric fields	Concepts
Deferred Errors	Build complex filters, check errors once at the end	Quickstart
Nested Logic	Combine filters with And/Or for complex queries	API
JSON Tags	Uses existing json tags - no new annotations needed	Concepts
Serializable Specs	Build filters from JSON for dynamic/LLM-generated queries	Specs

Why vecna?

• Catch typos early — Field name errors surface when building filters, not at query time
• Type safety — Comparison operators only work on numeric fields
• Zero new tags — Uses your existing json struct tags
• Provider agnostic — Filter AST translates to any vector database

Filters as Data

Filters can be built programmatically from serializable specs — enabling dynamic queries, stored filter configurations, and LLM-generated filters.

// Filter spec from JSON (API request, config file, LLM output)
specJSON := `{
    "op": "and",
    "children": [
        {"op": "eq", "field": "category", "value": "tech"},
        {"op": "gte", "field": "score", "value": 0.8}
    ]
}`

var spec vecna.FilterSpec
json.Unmarshal([]byte(specJSON), &spec)

// Convert to validated filter
builder, _ := vecna.New[Metadata]()
filter := builder.FromSpec(&spec)

if err := filter.Err(); err != nil {
    // Schema validation still applies - invalid fields caught here
}

The spec is validated against your schema. Field typos and type mismatches are caught at conversion time, not when the query hits your database.

Ecosystem

vecna powers the filter system in grub, providing schema-validated queries across vector database providers.

// In grub - vecna filters translate to provider-specific syntax
store, _ := grub.NewPinecone[Document](index, grub.WithNamespace("docs"))

filter := store.Filter().And(
    store.Filter().Where("category").Eq("tech"),
    store.Filter().Where("score").Gte(0.8),
)

results, _ := store.Query(ctx, embedding, grub.WithFilter(filter))

Supported providers: Pinecone, Qdrant, Weaviate, Milvus, pgvector.

Documentation

Learn

• Overview — What vecna is and why
• Quickstart — Get started in minutes
• Concepts — Core concepts and design
• Architecture — System design

Guides

• Specs — Building filters from JSON
• Testing — Testing with vecna
• Troubleshooting — Common issues

Reference

• API Reference — Function documentation
• Types Reference — Type definitions
• Operators — All filter operators
• pkg.go.dev — Generated docs

Contributing

See CONTRIBUTING.md for development workflow.

License

MIT - see LICENSE for details.