SyQL Query Language
SyQL (SynDB Query Language) is a declarative query language for neuroanatomical data. It resolves dataset metadata into optimized ClickHouse SQL, handles access control, and submits queries to the async job system.
Requires Academic verification.
Workflow
SyQL has a three-stage pipeline:
| Stage | Endpoint | What it does |
|---|---|---|
| Plan | POST /v1/syql/plan | Parse → validate → resolve metadata → return logical plan |
| Explain | POST /v1/syql/explain | Plan + compile to SQL → return compiled query and advisories |
| Execute | POST /v1/syql/exec | Plan + compile + submit to job queue → return job ID |
Use plan to validate syntax. Use explain to preview the generated SQL before committing to execution. Use exec when you’re ready to run.
Plan
curl -X POST -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
https://api.syndb.xyz/v1/syql/plan \
-d '{"query": "SELECT mesh_volume, brain_region FROM neurons WHERE dataset_id = '\''...'\'' LIMIT 1000"}'
Returns the parsed logical plan: resolved tables, columns, filters, and metadata.
Explain
curl -X POST -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
https://api.syndb.xyz/v1/syql/explain \
-d '{"query": "SELECT mesh_volume FROM neurons WHERE brain_region = '\''mushroom_body'\'' LIMIT 1000"}'
Returns:
- The compiled ClickHouse SQL
- Query advisories (e.g., missing indexes, large scan warnings)
- Estimated cost
Execute
curl -X POST -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
https://api.syndb.xyz/v1/syql/exec \
-d '{"query": "SELECT mesh_volume FROM neurons WHERE brain_region = '\''mushroom_body'\'' LIMIT 1000"}'
Returns a job_id. Track and download results via the Jobs System.
Cancel
curl -X POST -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
https://api.syndb.xyz/v1/syql/cancel \
-d '{"query_id": "..."}'
Federation Scope
Add "scope": "federation" to fan the query out across all federated nodes:
{
"query": "SELECT COUNT(*) FROM synapses GROUP BY dataset_id",
"scope": "federation"
}
See Cross-Cluster Queries for details.
Saved Queries
Frequently used SyQL queries can be saved for reuse. See Saved Queries.