Katoid for Visual Studio Code

Write, validate, execute and deploy Katoid queries, metrics, schemas and macros — directly from your editor.

What you get

• Native file types: .query.ktd, .metrics.ktd, .schema.ktd, .macros.ktd and .project.ktd with syntax highlighting, distinctive icons and JSON-Schema-aware editing (hover, autocomplete, structural validation).
• Run queries against the Katoid engine over HTTP or via the local CLI, with progressive results, gzip/deflate auto-detection and cancellation support.
• Interactive results as paginated tables (accordion or dropdown view), with CSV/JSON export and lazy-loaded debug panels showing the exact query sent and response received.
• Macros — Define reusable JSON fragments in .macros.ktd files and call them as ["$name", arg1, ...] inside queries and metrics. Comes with structural validation of macro definitions and inline diagnostics for invalid calls.
• Backend integration — Authenticate, upload queries and metrics, and validate schemas against the live engine, all from the editor.
• Project model — Wire your queries, metrics, schemas and macros together in a *.project.ktd file. Inline diagnostics catch missing files and inconsistent references across the project.
• Navigation — Go to Definition, Find References, Document Symbols and breadcrumbs across Katoid files.
• Multi-environment — Different engine URLs, datasources and query parameters per workspace folder (dev/staging/prod) using VS Code's native multi-root workspaces.

Quick start

1. Open or create a query

Create a file my_query.query.ktd with this minimal core:

{
  "facets": [
    {
      "name": "by_conversation",
      "group_events_by": [
        { "name": "conversation_id", "expr": ["event_field", "conversation_id"] }
      ],
      "calculators": [
        { "name": "conversation_id", "op": "any", "expr": ["event_field", "conversation_id"] }
      ]
    }
  ],
  "channels": [
    {
      "name": "ch_global",
      "sources": [
        {
          "facet": "by_conversation",
          "group_by": [{ "name": "Global", "expr": "Global" }],
          "calculators": [{ "name": "Total", "op": "count" }]
        }
      ]
    }
  ]
}

2. Point the extension at an engine

Open Settings (Ctrl+, / Cmd+,), search "Katoid", and configure either:

// HTTP mode
"katoid.engine.mode": "http",
"katoid.engine.http.url": "http://localhost:8080/query",
"katoid.engine.http.dataSource": "cbk1_cj"

or:

// CLI mode
"katoid.engine.mode": "cli",
"katoid.engine.cli.executablePath": "/path/to/katoidd",
"katoid.schema.path": "/path/to/schema",
"katoid.engine.cli.kbinsPath": "/path/to/data.kcb"

3. Run it

Press Ctrl+Shift+E (Mac: Cmd+Shift+E) or use the green play icon in the editor title bar.

A results panel opens with the data, paginated and exportable as CSV/JSON.

Commands

All commands are available from the Command Palette (Ctrl+Shift+P):

Right-click in the editor for the most common commands in context menus.

Configuration

A non-exhaustive list of the most useful settings. All of them are documented inline in the VS Code settings UI under the "Katoid" section.

Project file

A *.project.ktd at the root of your workspace ties together queries, metrics, schemas and macros. The settings below let you run a standalone query without one, but several features require a project file to work:

Minimal *.project.ktd example:

{
  "environments": {
    "dev": { "datasources": ["test_datasource"] }
  },
  "schemas": [
    { "name": "main", "file": "main.schema.ktd" }
  ],
  "queries": {
    "query_files": [
      { "name": "sample", "file": "sample.query.ktd", "targets": ["sample"] }
    ]
  },
  "metrics": {
    "metrics_files": [
      { "name": "Default", "file": "metrics/example.metrics.ktd" }
    ]
  },
  "macros": {
    "macros_files": [
      { "name": "Standard", "file": "macros/standard.macros.ktd" }
    ]
  }
}

Without it, executing a query still works (the extension falls back gracefully); the project-aware commands above will tell you they need a project file.

Engine

"katoid.engine.mode": "http"          // or "cli"
"katoid.engine.http.url": "http://localhost:8080/query"
"katoid.engine.http.dataSource": "cbk1_cj"
"katoid.engine.cli.executablePath": "/usr/local/bin/katoidd"
"katoid.engine.cli.kbinsPath": "/data/data.kcb"
"katoid.engine.cli.extraArgs": "--custom_param value"

Query parameters

"katoid.query.from": "2021-11-25"
"katoid.query.to": "2025-11-23"
"katoid.query.evalAsOf": "2025-11-25"
"katoid.query.decimation": 1.0
"katoid.query.stripCommentsBeforeSend": true

Results UI

"katoid.ui.resultsMode": "accordion"  // or "combobox"
"katoid.ui.maxRowsPerPage": 100
"katoid.ui.autoExpandSingleChannel": true
"katoid.ui.maxResponseSizeMB": 50

Debug

"katoid.debug.enableLogging": true   // detailed logs in the "Katoid" output channel

Multi-environment workspaces

Set up a single .code-workspace that opens prod, staging and dev folders side by side, each with its own engine URL, datasource and default dates. VS Code automatically picks the right configuration based on which folder the open file belongs to.

{
  "folders": [
    { "name": "prod",    "path": "queries/production" },
    { "name": "staging", "path": "queries/staging"    },
    { "name": "dev",     "path": "queries/development"}
  ],
  "settings": {
    // Settings shared by all environments
    "katoid.engine.cli.executablePath": "/usr/local/bin/katoidd",
    "katoid.ui.maxRowsPerPage": 100
  }
}

Then create queries/production/.vscode/settings.json, queries/staging/.vscode/settings.json, etc. with the environment-specific values (katoid.engine.http.url, katoid.engine.http.dataSource, katoid.query.from, ...).

The resulting layout on disk:

my-katoid-stuff/
├── katoid.code-workspace           # multi-root workspace definition
├── production/
│   ├── .vscode/
│   │   └── settings.json           # production-specific settings
│   ├── prod.project.ktd            # ONE project file at the folder root
│   ├── macros/
│   │   └── prod.macros.ktd
│   ├── metrics/
│   │   └── prod.metrics.ktd
│   └── queries/
│       └── monthly.query.ktd
├── staging/
│   ├── .vscode/
│   │   └── settings.json           # staging-specific settings
│   ├── staging.project.ktd         # ONE project file at the folder root
│   ├── macros/
│   │   └── staging.macros.ktd
│   ├── metrics/
│   │   └── staging.metrics.ktd
│   └── queries/
│       └── experiment.query.ktd
└── development/
    ├── .vscode/
    │   └── settings.json           # dev-specific settings
    ├── dev.project.ktd             # ONE project file at the folder root
    ├── macros/
    │   └── dev.macros.ktd
    ├── metrics/
    │   └── dev.metrics.ktd
    └── queries/
        └── scratch.query.ktd

One *.project.ktd per workspace folder, at the folder root. The extension searches each workspace folder's root for a single *.project.ktd (the search does not descend into subdirectories, and multiple project files in the same root cause an error). You cannot share a single *.project.ktd between environments by placing it at my-katoid-stuff/ — that directory is not a workspace folder, so the extension won't find it. If your environments share macros/metrics/schemas, point each project file's macros_files / metrics_files / schemas entries to relative paths that climb out with ../shared/..., or duplicate the contents per environment.

Open the workspace via File → Open Workspace from File... (or code katoid.code-workspace from a terminal). VS Code shows each folder as a separate root in the Explorer; when you edit a file under production/, the engine URL, datasource and default dates from production/.vscode/settings.json apply automatically — same for staging and dev.

Important: environment-specific settings only apply when the directory is declared as a workspace folder. Subfolders below a single workspace root will not pick them up.

Macros

.macros.ktd files let you define reusable JSON fragments:

{
  "macros": [
    {
      "name": "percentFormat",
      "params": ["precision"],
      "body": { "type": "d3Format", "params": [".${precision}~%"] },
      "description": "Format as percentage with given precision"
    }
  ]
}

And then call them from queries or metrics:

{ "alias": "rate_pct", "format": ["$percentFormat", 2] }

Troubleshooting

File icons not showing. Open the Command Palette and run Preferences: File Icon Theme, select Katoid File Icons.

Query execution fails. Open View -> Output -> Katoid and look for the error. Common causes:

• HTTP mode: katoid.engine.http.url not reachable.
• CLI mode: katoid.engine.cli.executablePath does not point to a valid binary.

Enable katoid.debug.enableLogging for verbose traces.

"Invalid JSON response" with binary noise. The HTTP client auto-detects gzip/deflate even without proper headers. If it still fails, the server may be using a different compression format — check the output channel for compression-detection logs.

Large response is slow. Increase katoid.ui.maxRowsPerPage, export to CSV/JSON instead of browsing in-panel, or add decimation to your query.

Schema validation errors I don't understand. Two layers run in parallel: structural (catches missing fields, wrong types, unknown properties) and semantic (catches engine-level inconsistencies). Hover over the squiggle for the full message and check the Problems panel — diagnostics are grouped by source.

Extension not activating. Requires VS Code ^1.80.0. Try Developer: Reload Window or reinstall.

License

MIT.