Skip to main content

SIDE Engine CLI

A reference for the SIDE Engine command line interface, focused on the most common workflows.

Install​

The CLI is a Python package. Use pip to install it:

pip install nextgres-side

Authentication and configuration​

Use side init to connect the CLI to your SIDE Engine account.

side init --api-key YOUR_API_KEY

Shell completion and help​

To make the CLI easier to use:

  • Install shell completion for your current shell: side --install-completion
  • Preview completion script without installing: side --show-completion
  • Get help for any command: side --help, side create-engine --help, side query --help

These commands show the full list of options and flags if you need more detail than this reference.

Table and data management​

SIDE Engine stores your data in tables. The typical workflow is:

  1. Create a table for your domain data.
  2. Insert data from a file (CSV / JSONL).
  3. Connect the table in your engine’s data block.

These commands mirror the table setup you see in the Quickstart and Hybrid Search docs.

Create a table from a data file​

Create a table and immediately load data from a local file:

side create-table-from-uri \
  --name pixar_movies \
  --uri ./data/pixar_movies.csv

Required flags

  • --name TABLE_NAME : Name of the table in SIDE Engine (e.g. pixar_movies ).
  • --uri PATH_OR_URI : Local file path or remote URI of the data file.

Create a table with an explicit schema​

If you want to control the schema (like the CUSTOM schemas in the examples), use create-table with a schema file:

side create-table --config table.yaml

Required flags

  • --config PATH : Path to a table config file that defines schema_type , name , and column_schema .

Insert data into an existing table​

Insert rows from a file into an existing table:

side table-insert \
  --name pixar_movies \
  --file ./data/pixar_movies.csv \
  --type csv

Required flags

  • --name TABLE_NAME : Existing table name.
  • --uri PATH_OR_URI : File containing rows (CSV / JSONL).

This is the CLI equivalent of using client.insert_table_rows("pixar_movies", records) in the Python examples.

Inspect, list, and delete tables​

List all tables:

side list-tables

View configuration for a single table:

side view-table --name pixar_movies

Delete a table:

side delete-table --name pixar_movies

Required flags

  • --name TABLE_NAME : Table to inspect or delete.

Seed demo tables​

Like engines, you can seed demo tables:

side table-seeds
side table-seed --name NAME_FROM_LIST

Required flags

  • --name SEED_NAME : One of the names shown in side table-seeds .

Engine management​

Engines define how your data is indexed, trained, and served.

Create an engine from a config file​

Use create-engine to create a new engine from a YAML configuration:

side create-engine --config engine.yaml

Required flags

  • --config PATH : Path to an engine config file (see engine-recipes for examples of data , index , training , deployment , and queries blocks).

Learn more about configuring engines - Engine basics

Update an existing engine​

Use update-engine when you change your engine config (for example, adding hybrid search or a new embedding):

side update-engine --name hybrid_search --config engine.yaml

Required flags

  • --name ENGINE_NAME : The name of the engine to update (e.g. semantic_search , hybrid_search ).
  • --config PATH : Updated engine config file.

Inspect and list engines​

List all engines in your account:

side list-engines

View a specific engine’s configuration (useful to compare to examples in engine-recipes):

side view-engine --name hybrid_search

Required flags

  • --name ENGINE_NAME : Engine to inspect.

Delete an engine you no longer need:

side delete-engine --name hybrid_search

Required flags

  • --name ENGINE_NAME : Engine to delete.

Seed demo engines​

Use a pre-built demo engine to explore SIDE Engine quickly:

side engine-seeds
side engine-seed --name NAME_FROM_LIST

Required flags

  • --name SEED_NAME : One of the names shown in side engine-seeds .

Views​

Views let you define reusable SQL transformations over existing tables. They are handy when you want to:

  • Normalize IDs to item_id / user_id .
  • Filter or join data before the engine sees it.

Common commands:

side create-view --config view.yaml
side list-views
side view-view --name my_view
side update-view --name my_view --config view.yaml
side delete-view --name my_view

Required flags

  • --config PATH : For create-view / update-view .
  • --name VIEW_NAME : For view-view , update-view , and delete-view .

Your engine data block can then point to a view instead of a raw table (see the query-based examples in engine-recipes).

Running queries with the CLI​

Once your engine is created and indexed, you can run ad-hoc and saved queries directly from the CLI.

Ad-hoc SIDEQL queries​

To experiment with queries like the SIDEQL examples in the Query Reference, use query:

side query \
  --engine hybrid_search \
  --query-file query.sql \
  --params '{"query": "Incredibles"}'

Required flags

  • --engine ENGINE_NAME : Engine to query (e.g. hybrid_search ).
  • --query-file PATH : File containing a SIDEQL query (see sideql docs for examples).

Common optional flags

  • --params JSON : JSON object of parameter values (e.g. {"query": "Incredibles"} ), matching $parameters.* in your query.

Execute saved queries​

If your engine config defines saved queries in the queries block (for example, search_products or personalized_feed from the engine recipes), you can execute them by name:

side execute-saved-query \
  --engine hybrid_search \
  --name search_products \
  --params '{"query_text": "Incredibles"}'

Required flags

  • --engine ENGINE_NAME : Engine that owns the saved query.
  • --name QUERY_NAME : Saved query name from the engine config.

Common optional flags

  • --params JSON : Parameters expected by the query (e.g. query_text , user_id , item_id ).

List all saved queries on an engine:

side list-saved-queries --engine hybrid_search

View the definition of a saved query (helpful when matching it with the queries block in YAML):

side view-saved-query \
  --engine hybrid_search \
  --name search_products

Required flags

  • --engine ENGINE_NAME
  • --name QUERY_NAME