Skip to main content
DocumentationLibraryReference
On this page

Integrations

VS Code extension

Install Kater's extension in VS Code, Cursor or Windsurf, sign in, and work on queries, models and scratch statements next to your other files.

Audience
Data teams
Prerequisites
  • VS Code, Cursor or Windsurf
  • The Kater CLI, signed in with kater login
  • A local copy of your content, made with kater git clone

Kater’s extension puts the workspace editor in VS Code, Cursor and Windsurf. Open a query file, and the Kater panel shows its fields, rows and chart. Open a model file, and it shows the model’s sources and joins. Each person signs in with their own Kater account, so the extension reads only what they can read.

Install and sign in

  1. Install the extension.

    In a terminal, run kater vscode install. It installs the extension, kater.kater, in each of VS Code, Cursor and Windsurf that it finds on your PATH. VS Code gets it from the Visual Studio Marketplace, and Cursor and Windsurf get it from Open VSX.

    Terminal window
    kater vscode install

    When it finds no editor, install one, then run the command again. In an editor, you can also search the Extensions view for Kater SQL and select Install.

    The extension starts Kater’s language server with the CLI that you installed, as kater lsp. So kater must be on the PATH that your editor sees.

  2. Open your local copy.

    In VS Code, select File › Open Folder… and open the folder that kater git clone made, such as ~/kater. The extension uses the first open folder that holds connections/. To use a different folder, set katerQuery.katerRoot to its full path.

  3. Sign in.

    Open the command palette and run Kater: Sign In. Your browser opens Kater’s sign-in page. When the page says “You’re signed in to Kater”, go back to VS Code. VS Code then says “Signed in to Kater as” and your email.

VS Code with the command palette open. The search box says Kater: Sign, and the list shows Kater: Sign In and Kater: Sign Out. The Kater panel below shows the Monthly Revenue query.
Run Kater: Sign In from the command palette.

The extension signs in to the same Kater as kater login, at the address that kater login saved. To use a different address, set katerQuery.apiUrl. The extension keeps your sign-in in VS Code’s secret storage. Kater: Sign Out removes it.

Work on a query

Open a query file, in a workspace’s query_contracts/ folder. The Kater panel, at the bottom of the window, opens the same query. It shows the fields you can add, the filters, the rows and the chart. A change in the panel changes the file, and a change in the file shows in the panel.

VS Code with monthly_revenue.sql open from the shop workspace. The Kater panel below shows the Monthly Revenue query: the Shop model's fields on the left with Currency selected, the filter bar, the rows by Order Month and Currency, and line charts of Revenue, Orders and Revenue (Running Sum).
The Kater panel follows the query you have open.
Part of the panelWhat it does
Layer picker, top leftSelects the Source Layer, the Shared Layer or one of your workspaces.
Workspace, Editor and DashboardShow the workspace’s overview, the open query, or the workspace’s dashboard.
Field pickerAdds a field to the query when you select its check box.
RunRuns the query and shows the new rows and chart.
Query tabs, at the bottomOpen another query of the same workspace.

Work on a shared model

Open a model file, in modeling/kater_objects/semantic_models/. The Kater panel shows the model’s sources, its joins as a diagram, its fields and its first rows.

VS Code with the shared model shop.sql open. The Kater panel shows 2 sources, 1 join and 21 fields, a diagram of Orders joined to Customers many to one, and the model's first rows.
A shared model in the Kater panel.

Try a statement in the Sandbox

The Kater Sandbox panel runs scratch files. A scratch file is a SQL file in your brainstorm folder, connections/<connection>/users/<your email>/brainstorm/. Only you and the people you share it with can read it, and it is never versioned.

  1. Make a scratch file.

    Open a model and run Kater: Open in Sandbox. Kater makes a scratch file that reads the model’s first 20 rows. To start from an empty file, run Kater: New Scratch File.

  2. Run it.

    Select Run in the Sandbox. In the file, ⌘↵ runs the statement at the cursor and ⇧⌘↵ runs every statement. On Windows and Linux, use Ctrl in place of ⌘.

The Kater Sandbox panel. A scratch file holds SELECT * FROM semantic.shop LIMIT 20, and the panel shows its 20 rows. The Shared Layer's models are listed on the left.
A scratch file and its rows in the Sandbox.

See who has access

The Kater Access view, in the Explorer, shows who has access to the file you have open. To see or change who has access to a folder, select the folder and run Kater: Manage Access…. Kater’s access rules apply here as they do in the portal. See Access.

Open Kater links in VS Code

In the portal, set Profile › Links › Open links in to VS Code. A link to a file then opens it in VS Code, at the line it names. When a link asks, you can also select Open in VS Code. Citation links in exported files open the same way.

If something does not work

What you seeWhat to do
“No Kater server is set.”Run kater login in a terminal, or set katerQuery.apiUrl. Then run Kater: Sign In again.
“Nothing answered at” an addressCheck your network and katerQuery.apiUrl, then try again.
“Kater cannot keep this result. This computer ran it without your Kater API”The extension’s kater is not signed in, or its profile names another Kater API. Run kater debug in a terminal and fix what it reports. Then run Developer: Reload Window. Warehouse settings never go in katerQuery.envFile.
The Kater panel does not show your fileCheck that the folder you opened holds connections/, or set katerQuery.katerRoot. The Kater Logs panel shows the details.

Next steps