# VGI documentation

> Protocol concepts and implementation documentation for building Vector Gateway Interface workers and clients.

- [VGI overview](https://query.farm/vgi/)
- [Documentation home](https://query.farm/vgi/docs/)
- [VGI Documentation](https://query.farm/vgi/docs/): Extend DuckDB with out-of-process functions written in Python, Go, TypeScript, Rust, Java, or C#. Start with the shared Concepts, then pick your SDK.


## Build with a coding agent

For a new worker, ask the developer to choose Python, TypeScript, Go, Rust, Java, or C# unless they already specified a language. Preserve the language of existing projects.

- [Agent quickstart](https://query.farm/vgi/build-with-an-agent/): Install the portable skill, choose a language, and build and test a worker locally.
- [Worked photo-catalog example](https://query.farm/vgi/photo-catalog-with-an-agent/): Follow a tested two-turn conversation, download the sample inputs or generated worker, and reproduce the SQL results.
- [VGI skills](https://github.com/Query-farm/vgi-skills): Versioned language recipes, SQL verification helpers, packaging, and fresh-session evaluations.
- [Test a Python worker](https://query.farm/vgi/docs/python/how-to/testing/)
- [Test a TypeScript worker](https://query.farm/vgi/docs/typescript/how-to/testing/)
Use published SDK versions and matching release examples. The skills verify through stock DuckDB 2.0.0. Configure the Query Farm extension repository, then INSTALL vgi FROM query_farm and LOAD vgi FROM query_farm. Haybarn is also supported.

## Concepts

The protocol, the worker model, and the five function shapes — whichever SDK you use.

- [Concepts](https://query.farm/vgi/docs/concepts/): What VGI is and why: extend DuckDB with out-of-process functions in any language. The worker model, the Apache Arrow data path, the function shapes, and how it all fits together.
- [Argument serialization](https://query.farm/vgi/docs/concepts/argument-serialization/): How VGI serializes a function's argument specifications to Apache Arrow schemas for IPC and DuckDB registration — the metadata keys, field order, and parse rules.
- [Function lifecycle](https://query.farm/vgi/docs/concepts/lifecycle/): When each VGI lifecycle method runs — bind, init, exchange, update, combine, and finalize — across scalar, table, table-in-out, aggregate, and buffering functions.
- [Secret types and credential discovery](https://query.farm/vgi/docs/concepts/secret-types/): How a VGI worker declares the credentials it needs as a DuckDB secret type, documents each field with vgi_doc, vgi_required and vgi_doc_url, and how clients read it all back with vgi_secret_types().
- [Starter templates](https://query.farm/vgi/docs/concepts/starter-templates/): GitHub template repositories for starting a VGI worker in Python, TypeScript, Go, Rust, Java or C#: tested examples, CI, Docker, signed releases and agent instructions, ready to rename.
- [Test a worker through SQL](https://query.farm/vgi/docs/concepts/testing/): Verify worker behavior, Arrow transport, and SQL binding with repeatable assertions in any VGI SDK language.

## C#

.NET 10 workers on Apache Arrow with all five function shapes and full catalog support.

- [C# starter template](https://github.com/Query-farm/vgi-starter-csharp): GitHub template repository with a tested worker, CI, Docker, signed releases and AGENTS.md; create a project with `gh repo create <name> --template Query-farm/vgi-starter-csharp` then `make init NAME=<name>`
- [Vector Gateway Interface for C#](https://query.farm/vgi/docs/csharp/): Build DuckDB scalar, table, aggregate, and catalog extensions in .NET 10 with Apache Arrow.
- [API overview](https://query.farm/vgi/docs/csharp/api/): The public QueryFarm.Vgi API, grouped by worker function and protocol concern.
- [Aggregate functions](https://query.farm/vgi/docs/csharp/api/aggregate/): Per-group state update, combine, and finalization.
- [Attributes & Arrow types](https://query.farm/vgi/docs/csharp/api/attributes-types/): Compute parameter annotations and Arrow type helpers.
- [Buffering functions](https://query.farm/vgi/docs/csharp/api/buffering/): Sink, combine, and source phases with durable cross-process state.
- [Catalogs](https://query.farm/vgi/docs/csharp/api/catalog/): Schemas, tables, views, macros, constraints, and scan metadata.
- [Protocol](https://query.farm/vgi/docs/csharp/api/protocol/): The VGI application-level request, result, and metadata contracts.
- [Scalar functions](https://query.farm/vgi/docs/csharp/api/scalar/): Vectorized one-row-to-one-value functions and reflection-driven ScalarFn dispatch.
- [Table functions](https://query.farm/vgi/docs/csharp/api/table/): Set-returning producers, bind/init parameters, and table argument declarations.
- [Table-in-out functions](https://query.farm/vgi/docs/csharp/api/table-in-out/): Streaming relation transforms that process Arrow record batches.
- [Worker & serving](https://query.farm/vgi/docs/csharp/api/worker/): The worker builder, registration surface, and supported process transports.
- [C# how-to guides](https://query.farm/vgi/docs/csharp/how-to/): Production tasks for QueryFarm.Vgi workers, from function shape through testing and deployment.
- [Expose a catalog](https://query.farm/vgi/docs/csharp/how-to/catalogs/): Register C# schemas, function-backed tables, views, and macros as a DuckDB catalog.
- [Add a custom COPY format](https://query.farm/vgi/docs/csharp/how-to/copy-formats/): Register C# table and buffering functions as DuckDB COPY FROM and COPY TO handlers.
- [Choose a function pattern](https://query.farm/vgi/docs/csharp/how-to/function-patterns/): Compare the five VGI function lifecycles implemented by QueryFarm.Vgi.
- [Integrate with the optimizer](https://query.farm/vgi/docs/csharp/how-to/pushdown-and-statistics/): Make C# VGI scans apply pushed filters and expose useful planning metadata.
- [Advertise result caching](https://query.farm/vgi/docs/csharp/how-to/result-caching/): Attach safe VGI cache-control metadata to C# functions and scan plans.
- [Call workers from .NET](https://query.farm/vgi/docs/csharp/how-to/rpc-client/): Understand QueryFarm.VgiRpc.Client and the boundary between generic RPC and a high-level VGI client.
- [Run and deploy a C# worker](https://query.farm/vgi/docs/csharp/how-to/running/): Build, publish, and serve QueryFarm.Vgi workers over supported transports.
- [Settings and secrets](https://query.farm/vgi/docs/csharp/how-to/settings-and-secrets/): Declare DuckDB settings and secret types, then request resolved values in C# functions.
- [Persist state across workers](https://query.farm/vgi/docs/csharp/how-to/state-storage/): Use mergeable byte state and IFunctionStorage instead of process-local C# objects.
- [Test a C# worker](https://query.farm/vgi/docs/csharp/how-to/testing/): Combine .NET unit tests, SQLLogicTest integration checks, and cross-language VGI conformance.
- [What's new in C#](https://query.farm/vgi/docs/csharp/release-notes/): Released versions, compatibility, and notable QueryFarm.Vgi changes.
- [1. Your first scalar function](https://query.farm/vgi/docs/csharp/tutorial/scalar/): Build and run a vectorized C# scalar VGI function from DuckDB.
- [2. Your first table function](https://query.farm/vgi/docs/csharp/tutorial/table/): Stream generated Arrow record batches from C# into DuckDB.

## Go

Single-binary workers on arrow-go, with struct-tag argument declarations.

- [Go starter template](https://github.com/Query-farm/vgi-starter-go): GitHub template repository with a tested worker, CI, Docker, signed releases and AGENTS.md; create a project with `gh repo create <name> --template Query-farm/vgi-starter-go` then `make init NAME=<name>`
- [Vector Gateway Interface for Go](https://query.farm/vgi/docs/go/): Build DuckDB scalar, table, and aggregate functions in Go on Apache Arrow — the official documentation for the vgi-go module.
- [Package vgi](https://query.farm/vgi/docs/go/api/): Overview of the vgi-go package: function shapes, declarative arguments, logging, and errors.
- [Aggregate functions](https://query.farm/vgi/docs/go/api/aggregate/): Per-group accumulation — update, combine, finalize — via the AggregateFunction interface.
- [Arguments](https://query.farm/vgi/docs/go/api/arguments/): Declaring, deriving, and binding function arguments.
- [Arrow helpers](https://query.farm/vgi/docs/go/api/arrow/): Building and emitting Arrow batches.
- [Cache control](https://query.farm/vgi/docs/go/api/cache-control/): Advertising a result as reusable by the client, via the CacheControl struct.
- [Catalogs](https://query.farm/vgi/docs/go/api/catalog/): Exposing schemas, tables, and views to ATTACH.
- [COPY formats](https://query.farm/vgi/docs/go/api/copy/): Custom COPY ... FROM readers and COPY ... TO writers.
- [Filter pushdown](https://query.farm/vgi/docs/go/api/filter-pushdown/): Receiving and evaluating pushed-down WHERE predicates.
- [Errors & logging](https://query.farm/vgi/docs/go/api/observability/): Error types and the named structured loggers.
- [Protocol & metadata](https://query.farm/vgi/docs/go/api/protocol/): Function metadata and the on-the-wire request/response types.
- [Scalar functions](https://query.farm/vgi/docs/go/api/scalar/): One row in, one value out — the per-row transform.
- [State storage](https://query.farm/vgi/docs/go/api/storage/): Cross-process state: the store, its backends, and state codecs.
- [Table functions](https://query.farm/vgi/docs/go/api/table/): Row generators: arguments in, a whole relation out.
- [Buffering functions](https://query.farm/vgi/docs/go/api/table-buffering/): Sink every row, combine, then stream the result back.
- [Table-in-out functions](https://query.farm/vgi/docs/go/api/table-in-out/): Stream a relation through, batch by batch.
- [Worker & serving](https://query.farm/vgi/docs/go/api/worker/): Registering functions and running a worker over each transport.
- [How-to guides](https://query.farm/vgi/docs/go/how-to/): Task-oriented guides for building Go VGI workers: function patterns, catalogs, serving, caching, COPY formats, and optimizer integration.
- [Argument tags](https://query.farm/vgi/docs/go/how-to/argument-tags/): The complete vgi:"..." struct-tag grammar — every key, the Go-type inference table, and the constraints DuckDB enforces.
- [Authenticate callers](https://query.farm/vgi/docs/go/how-to/authentication/): Require authentication for a Go VGI worker served over HTTP — bearer tokens, mTLS, JWT/OAuth — and read the caller's identity inside your functions.
- [Call a Go worker from code](https://query.farm/vgi/docs/go/how-to/calling-a-worker/): Drive a Go VGI worker from a program: through DuckDB with the haybarn engine, or directly with the Python vgi client.
- [Expose a catalog](https://query.farm/vgi/docs/go/how-to/catalogs/): How a Go worker presents itself to DuckDB as a catalog: schemas, function-backed tables, views, and ATTACH.
- [Add a custom COPY format](https://query.farm/vgi/docs/go/how-to/copy-formats/): Implement COPY ... FROM and COPY ... TO in a Go VGI worker — a remote format reader and a remote sink.
- [Report errors well](https://query.farm/vgi/docs/go/how-to/errors/): The typed errors a Go VGI worker can return, how they surface in DuckDB, and the wrapping mistake that silently loses them.
- [Function patterns](https://query.farm/vgi/docs/go/how-to/function-patterns/): The five VGI function shapes in Go — scalar, table, table-in-out, aggregate, buffering — each with a complete, runnable worker.
- [Integrate with the optimizer](https://query.farm/vgi/docs/go/how-to/pushdown-and-statistics/): Make a Go table function cooperate with DuckDB's optimizer: accept pushed-down filters and report column statistics.
- [Cache results on the client](https://query.farm/vgi/docs/go/how-to/result-caching/): Advertise cacheability from a Go worker: TTLs, validators, conditional revalidation, and per-partition or per-value reuse.
- [Serve over HTTP](https://query.farm/vgi/docs/go/how-to/serve-http/): Run a Go VGI worker as a network service — the four transports, the signing key every multi-process deployment needs, and what carries auth.
- [Settings, secrets, and global functions](https://query.farm/vgi/docs/go/how-to/settings-and-secrets/): Declare DuckDB settings and secret types from a Go worker, publish functions globally, and opt into transactions.
- [Persist state across workers](https://query.farm/vgi/docs/go/how-to/state-storage/): Cross-process state for Go VGI workers — the execution and attach scopes, the storage primitives, and how to pick a backend.
- [What's new](https://query.farm/vgi/docs/go/release-notes/): What changed in vgi-go through v0.22.0 — new capabilities, protocol bumps, and the breaking changes.
- [1. Your first scalar function](https://query.farm/vgi/docs/go/tutorial/scalar/): Build and run a scalar VGI function in Go, callable from DuckDB.
- [2. Add a table function](https://query.farm/vgi/docs/go/tutorial/table/): Grow the Go worker with a table function that generates rows from an argument.

## Java

JDK 25 workers on Arrow Java, wired up through Gradle.

- [Java starter template](https://github.com/Query-farm/vgi-starter-java): GitHub template repository with a tested worker, CI, Docker, signed releases and AGENTS.md; create a project with `gh repo create <name> --template Query-farm/vgi-starter-java` then `make init NAME=<name>`
- [Vector Gateway Interface for Java](https://query.farm/vgi/docs/java/): Build DuckDB scalar, table, and aggregate functions in Java on Apache Arrow — the official documentation for the farm.query:vgi artifact.
- [Package overview](https://query.farm/vgi/docs/java/api/): Orientation for farm.query:vgi — the five function shapes, the annotation vocabulary, and the map of every reference page.
- [Aggregate functions](https://query.farm/vgi/docs/java/api/aggregate/): Per-group accumulation with cross-process state combine.
- [Buffering functions](https://query.farm/vgi/docs/java/api/buffering/): Sink, combine, source — for output that depends on the whole input, via BufferingFinalizeProducer.
- [Cache control](https://query.farm/vgi/docs/java/api/cache-control/): Advertising a result as reusable by the client, through CacheControl.Builder.
- [Catalogs](https://query.farm/vgi/docs/java/api/catalog/): Presenting a worker as a database: schemas, tables, views, versioning.
- [Client](https://query.farm/vgi/docs/java/api/client/): Calling a VGI worker from Java, without DuckDB in the middle.
- [Function metadata & params](https://query.farm/vgi/docs/java/api/function/): The shared bind/process parameter types and the metadata every shape declares.
- [Protocol](https://query.farm/vgi/docs/java/api/protocol/): The wire shapes the worker and engine exchange.
- [Filter pushdown](https://query.farm/vgi/docs/java/api/pushdown/): Receiving the predicates DuckDB pushed toward the scan, and applying them.
- [Scalar functions](https://query.farm/vgi/docs/java/api/scalar/): One row in, one value out — the annotation-driven shape.
- [State storage](https://query.farm/vgi/docs/java/api/storage/): State that outlives one call or crosses worker processes, threaded through BoundStorage.
- [Table functions](https://query.farm/vgi/docs/java/api/table/): Set-returning producers, and the producer state that streams their rows.
- [Table-in-out functions](https://query.farm/vgi/docs/java/api/table-in-out/): Streaming a relation through batch by batch, via AnnotatedBatch and FinalExecute.
- [Arrow helpers](https://query.farm/vgi/docs/java/api/types/): Schema caching, per-type scalar helpers, and the type rules the annotations follow.
- [Worker & serving](https://query.farm/vgi/docs/java/api/worker/): The Worker builder, the transports, and what a worker declares about itself.
- [How-to guides](https://query.farm/vgi/docs/java/how-to/): Task-oriented guides for building Java VGI workers: function patterns, JVM flags and transports, catalogs.
- [Expose a catalog](https://query.farm/vgi/docs/java/how-to/catalogs/): Present a Java worker as a database — schemas, function-backed tables, views and macros DuckDB can query with ordinary qualified names.
- [Function patterns](https://query.farm/vgi/docs/java/how-to/function-patterns/): The five VGI function shapes in Java — scalar, table, table-in-out, aggregate, buffering — each with a complete, runnable worker.
- [Running a worker](https://query.farm/vgi/docs/java/how-to/running/): The JVM flags a Java VGI worker needs, why `launch:` matters, the four transports, and the shared-memory path that skips the pipe entirely.
- [What's new](https://query.farm/vgi/docs/java/release-notes/): Recent releases of farm.query:vgi, and what each one changes for a worker author.
- [1. Your first scalar function](https://query.farm/vgi/docs/java/tutorial/scalar/): Build and run a scalar VGI function in Java, callable from DuckDB.
- [2. Your first table function](https://query.farm/vgi/docs/java/tutorial/table/): Add a row-generating table function to your Java VGI worker, and scan it in parallel without duplicating rows.

## Python

PyArrow-native workers, type-annotated functions, the reference implementation.

- [Python starter template](https://github.com/Query-farm/vgi-starter-python): GitHub template repository with a tested worker, CI, Docker, signed releases and AGENTS.md; create a project with `gh repo create <name> --template Query-farm/vgi-starter-python` then `make init NAME=<name>`
- [Vector Gateway Interface for Python](https://query.farm/vgi/docs/python/): Build DuckDB scalar, table, and aggregate functions in Python on Apache Arrow — the official documentation for the vgi-python module.
- [vgi.aggregate_function](https://query.farm/vgi/docs/python/api/vgi-aggregate_function/): Framework for implementing aggregate functions.
- [vgi.arguments](https://query.farm/vgi/docs/python/api/vgi-arguments/): Argument parsing and validation for VGI functions.
- [vgi.auth](https://query.farm/vgi/docs/python/api/vgi-auth/): Convenience re-exports of authentication types from vgi-rpc.
- [vgi.cache_control](https://query.farm/vgi/docs/python/api/vgi-cache_control/): Result-cache control metadata (vgi.cache.*).
- [vgi.catalog](https://query.farm/vgi/docs/python/api/vgi-catalog/): VGI Catalog Interface for exposing catalogs, schemas, tables, and views.
- [vgi.client](https://query.farm/vgi/docs/python/api/vgi-client/): VGI client package for communicating with VGI workers.
- [vgi.copy_from_function](https://query.farm/vgi/docs/python/api/vgi-copy_from_function/): Base class for custom COPY ... FROM format readers.
- [vgi.copy_to_function](https://query.farm/vgi/docs/python/api/vgi-copy_to_function/): Base class for custom COPY ... TO format writers.
- [vgi.exceptions](https://query.farm/vgi/docs/python/api/vgi-exceptions/): Exception classes for VGI.
- [vgi.function_storage](https://query.farm/vgi/docs/python/api/vgi-function_storage/): Storage for VGI function state.
- [vgi.invocation](https://query.farm/vgi/docs/python/api/vgi-invocation/): Response types for the VGI protocol.
- [vgi.logging_config](https://query.farm/vgi/docs/python/api/vgi-logging_config/): Shared logging configuration for VGI worker CLIs.
- [vgi.metadata](https://query.farm/vgi/docs/python/api/vgi-metadata/): Function metadata for introspection, documentation, and DuckDB registration.
- [vgi.otel](https://query.farm/vgi/docs/python/api/vgi-otel/): VGI application-level OpenTelemetry and Sentry instrumentation.
- [vgi.profiling](https://query.farm/vgi/docs/python/api/vgi-profiling/): Opt-in CPU profiling for VGI worker processes.
- [vgi.scalar_function](https://query.farm/vgi/docs/python/api/vgi-scalar_function/): Scalar functions: per-row transforms with single-column output.
- [vgi.secret_protocol](https://query.farm/vgi/docs/python/api/vgi-secret_protocol/): VGI secret protocol — the wire contract for Orchard's standalone secret service.
- [vgi.secret_service](https://query.farm/vgi/docs/python/api/vgi-secret_service/): Standalone serving harness for the VGI secret protocol (Orchard).
- [vgi.serve](https://query.farm/vgi/docs/python/api/vgi-serve/): Zero-boilerplate CLI for serving VGI workers.
- [vgi.table_buffering_function](https://query.farm/vgi/docs/python/api/vgi-table_buffering_function/): Framework for implementing table sink+source functions.
- [vgi.table_filter_pushdown](https://query.farm/vgi/docs/python/api/vgi-table_filter_pushdown/): Filter pushdown AST classes for table functions.
- [vgi.table_function](https://query.farm/vgi/docs/python/api/vgi-table_function/): Base classes for table functions with cardinality hints and callback-based processing.
- [vgi.table_in_out_function](https://query.farm/vgi/docs/python/api/vgi-table_in_out_function/): Framework for implementing streaming table-in-table-out functions.
- [vgi.transactor](https://query.farm/vgi/docs/python/api/vgi-transactor/): db-transactor — transactional database access for VGI workers.
- [vgi.worker](https://query.farm/vgi/docs/python/api/vgi-worker/): VGI Worker base class for hosting user-defined functions and catalogs.
- [How-to guides](https://query.farm/vgi/docs/python/how-to/): Task-oriented guides for building VGI workers: function patterns, catalogs, state, auth, and optimizer integration.
- [Aggregate functions](https://query.farm/vgi/docs/python/how-to/aggregate-functions/): Deep reference for the VGI aggregate shape: initial_state / update / combine / finalize contracts, dynamic output types, multi-arg and weighted aggregates, and the streaming-partitioned opt-in.
- [Authentication](https://query.farm/vgi/docs/python/how-to/authentication/): Authenticate callers to a VGI worker served over HTTP — bearer tokens and JWT/OAuth — and read the AuthContext in your functions. Auth is an HTTP-transport concern, provided by vgi-rpc.
- [Catalog interface](https://query.farm/vgi/docs/python/how-to/catalog-interface/): Hand-written guidance for VGI's catalog interface: declarative catalogs, scan delegation, and safely logging attach options and opaque data.
- [Expose a catalog](https://query.farm/vgi/docs/python/how-to/catalogs/): How to expose a VGI worker as a DuckDB catalog: schemas, function qualification, and tables/views via ATTACH.
- [Use the CLI](https://query.farm/vgi/docs/python/how-to/cli/): Invoke VGI functions, manage catalogs, and serve workers from the command line without writing code.
- [CLI reference](https://query.farm/vgi/docs/python/how-to/cli-reference/): Complete reference for the vgi-client and vgi-serve command-line tools: every subcommand, flag, environment variable, and the bundled fixture functions.
- [Column statistics](https://query.farm/vgi/docs/python/how-to/column-statistics/): Report per-column min/max, null counts, and distinct counts so DuckDB's optimizer can prune scans, order joins better, and push down filters.
- [Add a custom COPY format](https://query.farm/vgi/docs/python/how-to/copy-formats/): Implement COPY ... FROM and COPY ... TO in a VGI worker: a remote format reader and a remote sink, with credentials.
- [Filter pushdown wire format](https://query.farm/vgi/docs/python/how-to/filter-pushdown/): The hybrid JSON + Arrow wire format DuckDB uses to push WHERE-clause predicates to a table function — the low-level contract behind the decoded PushdownFilters API.
- [Function patterns](https://query.farm/vgi/docs/python/how-to/function-patterns/): The five VGI function shapes — scalar, table, table-in-out, aggregate, buffering — each with a complete, runnable worker.
- [Function API](https://query.farm/vgi/docs/python/how-to/generator-api/): Deep reference for the callback APIs behind the scalar, table, and table-in-out shapes: the bind / init / process / finalize method contracts, the @bind_fixed_schema and @init_single_worker decorators, ProcessParams, and output-schema rules.
- [Publish global functions](https://query.farm/vgi/docs/python/how-to/global-functions/): Publish selected worker functions into DuckDB's global namespace so they can be called without naming the attached catalog.
- [Function metadata](https://query.farm/vgi/docs/python/how-to/metadata/): Give a function a nested Meta class for introspection — its SQL name, description, examples, parallelism, and optimizer hints — across every function shape.
- [Integrate with the optimizer](https://query.farm/vgi/docs/python/how-to/pushdown-and-statistics/): How to integrate VGI table functions with DuckDB's optimizer: accept pushed-down filters and report column statistics.
- [Use VGI from a Python app](https://query.farm/vgi/docs/python/how-to/python-app/): Drive a VGI worker from your own Python program with the haybarn engine — the DuckDB-compatible package that ships the vgi extension.
- [Cache results on the client](https://query.farm/vgi/docs/python/how-to/result-caching/): Advertise cacheability from a VGI worker: TTLs, validators, conditional revalidation, and per-partition or per-value reuse.
- [Serve over HTTP](https://query.farm/vgi/docs/python/how-to/serve-http/): Run a VGI worker as an HTTP network service: serve it with vgi-serve --http, attach from DuckDB, and call it from the Python Client.
- [Shared storage backends](https://query.farm/vgi/docs/python/how-to/shared-storage/): Configure where VGI shared state is stored — SQLite (default), Azure SQL, or Cloudflare Durable Objects — and implement a custom backend.
- [Persist state across workers](https://query.farm/vgi/docs/python/how-to/state-storage/): How to give VGI functions shared, persistent state across worker processes — the default SQLite backend and cloud alternatives.
- [Test a Python worker](https://query.farm/vgi/docs/python/how-to/testing/): Test Python business logic and verify the real VGI worker through DuckDB or Haybarn SQL, with null and multi-batch cases.
- [What's new](https://query.farm/vgi/docs/python/release-notes/): Everything that changed in vgi-python between 0.8 and 0.28 — new capabilities, protocol bumps, and the two breaking changes.
- [1. Your first scalar function](https://query.farm/vgi/docs/python/tutorial/scalar/): Build and run a scalar VGI function callable from DuckDB.
- [2. Add a table function](https://query.farm/vgi/docs/python/tutorial/table/): Grow the worker with a table function that generates rows from an argument.

## Rust

Zero-overhead workers on arrow-rs, across three composable crates.

- [Rust starter template](https://github.com/Query-farm/vgi-starter-rust): GitHub template repository with a tested worker, CI, Docker, signed releases and AGENTS.md; create a project with `gh repo create <name> --template Query-farm/vgi-starter-rust` then `make init NAME=<name>`
- [Vector Gateway Interface for Rust](https://query.farm/vgi/docs/rust/): Build DuckDB scalar, table, and aggregate functions in Rust on Apache Arrow — the official documentation for the vgi crate.
- [Package overview](https://query.farm/vgi/docs/rust/api/): Orientation for the vgi crate — the five function traits, the three crates the public surface spans, and the map of every reference page.
- [Aggregate functions](https://query.farm/vgi/docs/rust/api/aggregate/): Per-group accumulation: aggregate_bind, update, combine, and finalize on BoundAggregate.
- [Arguments](https://query.farm/vgi/docs/rust/api/arguments/): Declaring a signature, and reading the values that arrive, one arg at a time.
- [Buffering functions](https://query.farm/vgi/docs/rust/api/buffering/): Sink, combine, source — for output that depends on the whole input, via TableBufferingFunction.
- [Cache control](https://query.farm/vgi/docs/rust/api/cache-control/): Advertising a result as reusable by the client, through the CACHE_ETAG_KEY and CACHE_EXPIRES_KEY result metadata.
- [Catalogs](https://query.farm/vgi/docs/rust/api/catalog/): Presenting a worker as a database — schemas, tables, views, and macros — as catalog traits implement them.
- [Client](https://query.farm/vgi/docs/rust/api/client/): Calling a VGI worker from Rust, without DuckDB in the middle.
- [COPY formats](https://query.farm/vgi/docs/rust/api/copy/): Reading and writing your own format through COPY … FROM / TO, via CopyFromFunction and CopyFromReadContext.
- [Protocol & Arrow](https://query.farm/vgi/docs/rust/api/protocol/): Wire shapes, the Arrow IPC helpers, and the numeric utilities.
- [Pushdown & statistics](https://query.farm/vgi/docs/rust/api/pushdown/): Receiving the predicates DuckDB pushed toward the scan, and reporting what you know.
- [Scalar functions](https://query.farm/vgi/docs/rust/api/scalar/): One row in, one value out — the simplest function shape — declared with ArgSpec.
- [Secrets & settings](https://query.farm/vgi/docs/rust/api/secrets/): Credentials and session settings a worker declares and reads.
- [State storage](https://query.farm/vgi/docs/rust/api/storage/): State that outlives one call or crosses worker processes, backed by FunctionStorage and FsStorage.
- [Table functions](https://query.farm/vgi/docs/rust/api/table/): Set-returning producers, and the producer that streams their rows.
- [Table-in-out functions](https://query.farm/vgi/docs/rust/api/table-in-out/): Streaming a relation through batch by batch, calling emit/emit_with as each one is ready.
- [Worker & serving](https://query.farm/vgi/docs/rust/api/worker/): Building a worker, wiring its state, and putting it on a transport.
- [How-to guides](https://query.farm/vgi/docs/rust/how-to/): Task-oriented guides for building Rust VGI workers: function patterns, transports and the wasm target, catalogs, caching, and error reporting.
- [Expose a catalog](https://query.farm/vgi/docs/rust/how-to/catalogs/): Present a Rust worker as a database — schemas, function-backed tables, and views DuckDB can query with ordinary qualified names.
- [Report errors well](https://query.farm/vgi/docs/rust/how-to/errors/): How a Rust VGI worker reports failure — the RpcError constructors, what each one means to DuckDB, and the panic that takes the worker with it.
- [Function patterns](https://query.farm/vgi/docs/rust/how-to/function-patterns/): The five VGI function shapes in Rust — scalar, table, table-in-out, aggregate, buffering — each with a complete, runnable worker.
- [Cache results on the client](https://query.farm/vgi/docs/rust/how-to/result-caching/): Advertise a Rust worker's result as reusable so repeat queries never reach it — TTLs, validators, and the diagnostics that prove it engaged.
- [Transports & runtimes](https://query.farm/vgi/docs/rust/how-to/transports/): The four ways a Rust VGI worker can be served — stdio, Unix socket, TCP, HTTP — and the wasm32 target that runs the worker inside the browser next to DuckDB-WASM.
- [What's new](https://query.farm/vgi/docs/rust/release-notes/): Recent releases of the vgi crate, and what each one changes for a worker author.
- [1. Your first scalar function](https://query.farm/vgi/docs/rust/tutorial/scalar/): Build and run a scalar VGI function in Rust, callable from DuckDB.
- [2. Your first table function](https://query.farm/vgi/docs/rust/tutorial/table/): Add a row-generating table function to your Rust VGI worker, and call it in a FROM clause.

## TypeScript

Node, Bun and Deno workers with fully typed function configs.

- [TypeScript starter template](https://github.com/Query-farm/vgi-starter-typescript): GitHub template repository with a tested worker, CI, Docker, signed releases and AGENTS.md; create a project with `gh repo create <name> --template Query-farm/vgi-starter-typescript` then `make init NAME=<name>`
- [Vector Gateway Interface for TypeScript](https://query.farm/vgi/docs/typescript/): Build DuckDB scalar, table, and aggregate functions in TypeScript on Apache Arrow — the official documentation for the @query-farm/vgi package.
- [Package overview](https://query.farm/vgi/docs/typescript/api/): Orientation for @query-farm/vgi — the four entry points, the five function factories, and the map of every reference page.
- [Aggregate functions](https://query.farm/vgi/docs/typescript/api/aggregate/): Per-group accumulation — update, combine, finalize — configured with AggregateFunctionConfig.
- [Arguments](https://query.farm/vgi/docs/typescript/api/arguments/): Declaring a signature, and reading the values that arrive, via ArgumentSpec and Arguments.
- [Batch helpers](https://query.farm/vgi/docs/typescript/api/arrow-helpers/): Building, reading, projecting and serializing record batches.
- [Arrow types](https://query.farm/vgi/docs/typescript/api/arrow-types/): The type factories, the erased facade shapes, and the predicates that discriminate them.
- [Cache control](https://query.farm/vgi/docs/typescript/api/cache-control/): Marking a result reusable by the client with the CACHE_ETAG_KEY/CACHE_EXPIRES_KEY metadata constants.
- [Catalogs](https://query.farm/vgi/docs/typescript/api/catalog/): Presenting a worker as a database — schemas, tables, views, and macros — configured through the catalog interface.
- [Client](https://query.farm/vgi/docs/typescript/api/client/): Calling a VGI worker from TypeScript, without DuckDB in the middle.
- [Value representations](https://query.farm/vgi/docs/typescript/api/codec/): rich vs raw, the branded unit types, and the codec that converts between them.
- [COPY formats](https://query.farm/vgi/docs/typescript/api/copy/): Reading and writing your own format through COPY … FROM / TO, configured with CopyFromFunctionConfig.
- [Errors](https://query.farm/vgi/docs/typescript/api/errors/): The typed errors a worker raises, and how they reach the caller.
- [Filter pushdown](https://query.farm/vgi/docs/typescript/api/filter-pushdown/): Receiving the predicates DuckDB pushed toward the scan.
- [Protocol & metadata](https://query.farm/vgi/docs/typescript/api/metadata/): Enums, protocol shapes, secrets, and the function metadata DuckDB reads.
- [Scalar functions](https://query.farm/vgi/docs/typescript/api/scalar/): One row in, one value out — the simplest function shape — declared with defineScalarFunction.
- [State storage](https://query.farm/vgi/docs/typescript/api/storage/): State that outlives one call or crosses worker processes, read back from BoundStorage after a bind.
- [Table functions](https://query.farm/vgi/docs/typescript/api/table/): Set-returning producers, with the optimizer hooks that make them fast.
- [Buffering functions](https://query.farm/vgi/docs/typescript/api/table-buffering/): Sink, combine, source — for output that depends on the whole input, via defineTableBufferingFunction.
- [Table-in-out functions](https://query.farm/vgi/docs/typescript/api/table-in-out/): Streaming a relation through batch by batch, with defineRowTransformFunction/defineTableInOutFunction.
- [Re-exported from vgi-rpc](https://query.farm/vgi/docs/typescript/api/vgi-rpc-reexports/): Names @query-farm/vgi re-exports from the RPC layer, and where they are documented.
- [Worker & serving](https://query.farm/vgi/docs/typescript/api/worker/): Building a worker and putting it on a transport, via buildVgiProtocol.
- [How-to guides](https://query.farm/vgi/docs/typescript/how-to/): Task-oriented guides for building TypeScript VGI workers: function patterns, value representations, runtimes, catalogs, serving, caching, and the client.
- [Expose a catalog](https://query.farm/vgi/docs/typescript/how-to/catalogs/): Present a TypeScript worker as a database — schemas, function-backed tables, and views DuckDB can query with ordinary qualified names.
- [Call a worker from TypeScript](https://query.farm/vgi/docs/typescript/how-to/client/): Drive a VGI worker directly with VgiClient — no DuckDB in the middle. The fastest way to test a worker, and the basis of the browser client.
- [Report errors well](https://query.farm/vgi/docs/typescript/how-to/errors/): The typed errors a TypeScript VGI worker can throw, how they reach the person running the query, and the stack trace that travels with them.
- [Function patterns](https://query.farm/vgi/docs/typescript/how-to/function-patterns/): The five VGI function shapes in TypeScript — scalar, table, table-in-out, aggregate, buffering — each with a complete, runnable worker.
- [Cache results on the client](https://query.farm/vgi/docs/typescript/how-to/result-caching/): Advertise a TypeScript worker's result as reusable so repeat queries never reach it — TTLs, validators, and the diagnostics that prove it engaged.
- [Runtimes & entry points](https://query.farm/vgi/docs/typescript/how-to/runtimes/): Where a TypeScript VGI worker can run — Node, Bun, Cloudflare Workers, the browser — and which of the four subpath exports each one wants.
- [Serve over HTTP](https://query.farm/vgi/docs/typescript/how-to/serve-http/): Run a TypeScript VGI worker as a network service with serveVgiWorker — the signing key every real deployment needs, CORS, and the landing surface you get for free.
- [Test a TypeScript worker](https://query.farm/vgi/docs/typescript/how-to/testing/): Verify TypeScript VGI workers through a real SQL engine, including BIGINT precision, null handling, and multiple Arrow batches.
- [Value representations](https://query.farm/vgi/docs/typescript/how-to/value-representations/): What a column's values actually are in TypeScript — rich vs raw, why decimals are unscaled bigints, and the two access paths that do not agree.
- [What's new](https://query.farm/vgi/docs/typescript/release-notes/): Recent releases of @query-farm/vgi, and what each one changes for a worker author.
- [1. Your first scalar function](https://query.farm/vgi/docs/typescript/tutorial/scalar/): Build and run a scalar VGI function in TypeScript, callable from DuckDB.
- [2. Your first table function](https://query.farm/vgi/docs/typescript/tutorial/table/): Add a row-generating table function to your TypeScript VGI worker, and call it in a FROM clause.