GigAPI Query Engine

GigAPI Go provides a Flight SQL and HTTP interface to query time-series using GigAPI Catalog Metadata and DuckDB

Warning

GigAPI is an open beta developed in public. Bugs and changes should be expected. Use at your own risk.

Quick Start

Docker

Run gigapi-querier using Docker making sure the proper data folder or S3 bucket is provided

gigapi-querier:
  image: ghcr.io/gigapi/gigapi-querier:latest
  container_name: gigapi-querier
  hostname: gigapi-querier
  volumes:
    - ./data:/data
  ports:
    - "8080:8080"
    - "8082:8082"
  environment:
    - DATA_DIR=/data
    - PORT=8080

Build

# Build from source
go generate
go build -o gq .

# Start the server
PORT=8080 DATA_DIR=./data ./gigapi

Configuration

• PORT: Main server port (default: 8080)
• FLIGHTSQL_PORT: FlightSQL API server port (default: 8082)
• DATA_DIR: Path to data directory (default: ./data)
• DISABLE_UI: Disable web UI (optional)

API Endpoints

Query Data

Query Processing Logic

1. Parse SQL query to extract FROM db.table and time range
2. Find relevant parquet files using catalog metadata
3. Use DuckDB to execute optimized queries against selected files
4. Post-process results to handle BigInt timestamps

API

$ curl -X POST "http://localhost:8080/query?db=mydb" \
  -H "Content-Type: application/json"  \
  -d '{"query": "SELECT time, location, temperature FROM weather WHERE time >= '2025-04-01T00:00:00'"}'

CLI

The GigAPI Querier can also be used in CLI mode to execute an individual query

$ ./gigapi --query "SELECT count(*), avg(temperature) FROM weather" --db mydb

FlightSQL

GigAPI data can be accessed using FlightSQL GRPC clients in any language

from flightsql import connect, FlightSQLClient
client = FlightSQLClient(host='localhost',port=8082,insecure=True,metadata={'bucket':'hep'})
conn = connect(client)
cursor = conn.cursor()
cursor.execute('SELECT 1, version()')
print("rows:", [r for r in cursor])

UI

A quick and dirty query user-interface is also provided for testing

Grafana

GigAPI can be used from Grafana using the InfluxDB3 Flight GRPC Datasource

Got Questions?

License

Gigapipe is released under the GNU Affero General Public License v3.0 ©️ HEPVEST BV, All Rights Reserved.