Getting Started

JSONQL lets you describe queries in JSON, execute them through SDKs, and keep your data contract consistent across systems.

1. Pick an SDK

Choose the SDK for your runtime:

SDK	Install	Frameworks
Go	go get github.com/jsonql-standard/jsonql-go	Gin, Echo, net/http
TypeScript	npm install @jsonql-standard/jsonql-ts	Express, Fastify, NestJS
Python	pip install jsonql-py	Flask, FastAPI, Django
Java	Maven dependency	Spring Boot, Jakarta EE

2. Define a Query

JSONQL queries are JSON documents. A minimal example:

{
  "version": "1.0",
  "fields": ["id", "name", "email"],
  "where": {
    "status": { "eq": "active" }
  },
  "sort": "-created_at",
  "limit": 20
}

3. Send It

Post the query to any JSONQL-powered endpoint:

curl -X POST http://localhost:8080/users \
  -H "Content-Type: application/json" \
  -d '{"fields": ["id", "name"], "where": {"status": {"eq": "active"}}, "limit": 10}'

Response:

{
  "data": [
    { "id": 1, "name": "Alice" },
    { "id": 2, "name": "Bob" }
  ]
}

4. Include Relationships

Fetch nested data with include:

{
  "fields": ["id", "name"],
  "include": {
    "posts": {
      "fields": ["id", "title"],
      "sort": "-created_at",
      "limit": 3
    }
  }
}

5. Use the Query Builder

Each SDK provides a fluent builder for constructing queries programmatically. For example, in Python:

from jsonql import QueryBuilder
from jsonql.conditions import eq, gt, field, and_

query = (
    QueryBuilder()
    .from_table("users")
    .select("id", "name")
    .where(and_(field("status", eq("active")), field("age", gt(18))))
    .order_by("-created_at")
    .limit(10)
    .build()
)

Or in Go:

q := builder.New().
    From("users").
    Select("id", "name").
    Where(map[string]any{"status": map[string]any{"eq": "active"}}).
    AndWhere(map[string]any{"age": map[string]any{"gte": 18}}).
    OrderBy("-created_at").
    Limit(10).
    Build()

6. Run Compliance Tests

Verify your adapter works correctly by running the compliance suite:

cd jsonql-tests
./run_tests.sh --target your-adapter

All 63 compliance configurations (Go + TypeScript + Java + Python) pass 135/135 tests across 5 databases. See Compliance Testing for details.

Next Steps

• Dive into the Developer Guide
• Explore the Query Language reference
• Read the Specification