Skip to content

index.md

Latest commit

 

History

History
47 lines (36 loc) · 2.75 KB

index.md

File metadata and controls

47 lines (36 loc) · 2.75 KB
Raw
description vgi-python API reference — functions, arguments, worker, client, catalogs, state storage, filter pushdown, auth, and observability.

API Reference

Where to Start

New to VGI? Follow this path:

  1. Pick a function pattern — ScalarFunction, TableFunctionGenerator, TableInOutFunction, or AggregateFunction (Functions)
  2. Declare arguments — Param, ConstParam, Returns, TableInput (Arguments & Schema)
  3. Host them in a worker — subclass Worker, then vgi-serve it over stdio or HTTP (Worker & Serving)
  4. Connect from DuckDB or Python — the DuckDB extension or the Python Client (Client)

Everything else — catalogs, state storage, filter pushdown, auth, observability — is optional and added incrementally.

Modules

Module Description Required?
Functions ScalarFunction, TableFunctionGenerator, TableInOutFunction, AggregateFunction, Function Yes
Arguments & Schema Param, ConstParam, Returns, TableInput, ArgumentSpec, schema Yes
Worker & Serving Worker, the vgi-serve entry point Yes
Client Client, ClientError, catalog client helpers If calling workers from Python
Catalogs Catalog, Schema, Table, View, CatalogStorage If exposing a catalog
State Storage FunctionStorage, SQLite / Azure SQL / Cloudflare DO backends If functions keep state
Metadata & Protocol ResolvedMetadata, FunctionExample, FunctionStability, protocol types For introspection
Filter Pushdown PushdownFilters, filter node types, deserialize_filters If accepting pushed-down filters
Auth & Secrets AuthContext, CallContext, bearer/JWT authenticators, secret protocol HTTP: [http]; JWT: [oauth]
Observability OpenTelemetry tracing, worker logging configuration [otel] for tracing
HTTP Worker page, blob storage, request-size middleware pip install vgi-python[http]
Transactor TransactorClient, TransactorProtocol [transactor] extra and a compatible engine build
Exceptions VGI exception types —

Import Convention

The most common symbols are re-exported from the top-level vgi package:

from vgi import ScalarFunction, TableInOutFunction, AggregateFunction, Param, Returns, Worker

Subpackages (vgi.catalog, vgi.client, vgi.http, vgi.transactor) are imported explicitly. Optional modules require their corresponding extras to be installed.