ml | CLI commands

Manage SurrealML models within an existing database. The command has two subcommands: one imports a trained model into a database, the other exports a model that is already stored there.

Note

Before you begin - make sure you’ve installed SurrealDB.

Usage

surreal ml [OPTIONS] <COMMAND>

Subcommand	Purpose
`surreal ml import`	Import a SurrealML model into an existing database.
`surreal ml export`	Export a SurrealML model from an existing database.
`surreal ml help`	Print this message or the help of the given subcommand.

Command help

To see the help information and usage instructions, in a terminal run the surreal ml --help command without any further arguments. This command gives general information on the arguments, inputs, and additional options for the ml command.

surreal ml --help

The output of the above command:

Manage SurrealML models within an existing database

Usage: surreal ml [OPTIONS] <COMMAND>

Commands:
  import  Import a SurrealML model into an existing database
  export  Export a SurrealML model from an existing database
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

Logging:
  -l, --log <LOG>                              The logging level for the command-line tool [env: SURREAL_LOG=] [default: info] [possible values: none, full, error, warn, info, debug, trace]
      --log-format <LOG_FORMAT>                The format for terminal log output [env: SURREAL_LOG_FORMAT=] [default: text] [possible values: text, json]
      --log-socket <LOG_SOCKET>                Send logs to the specified host:port [env: SURREAL_LOG_SOCKET=]
      --log-file-level <LOG_FILE_LEVEL>        Override the logging level for file output [env: SURREAL_LOG_FILE_LEVEL=] [possible values: none, full, error, warn, info, debug, trace]
      --log-otel-level <LOG_OTEL_LEVEL>        Override the logging level for OpenTelemetry output [env: SURREAL_LOG_OTEL_LEVEL=] [possible values: none, full, error, warn, info, debug, trace]
      --log-socket-level <LOG_SOCKET_LEVEL>    Override the logging level for unix socket output [env: SURREAL_LOG_SOCKET_LEVEL=] [possible values: none, full, error, warn, info, debug, trace]
      --log-socket-format <LOG_SOCKET_FORMAT>  The format for socket output [env: SURREAL_LOG_SOCKET_FORMAT=] [default: text] [possible values: text, json]
      --log-file-enabled                       Whether to enable log file output [env: SURREAL_LOG_FILE_ENABLED=]
      --log-file-path <LOG_FILE_PATH>          The directory where log files will be stored [env: SURREAL_LOG_FILE_PATH=] [default: logs]
      --log-file-name <LOG_FILE_NAME>          The name of the log file [env: SURREAL_LOG_FILE_NAME=] [default: surrealdb.log]
      --log-file-format <LOG_FILE_FORMAT>      The format for log file output [env: SURREAL_LOG_FILE_FORMAT=] [default: text] [possible values: text, json]
      --log-file-rotation <LOG_FILE_ROTATION>  The log file rotation interval [env: SURREAL_LOG_FILE_ROTATION=] [default: daily] [possible values: daily, hourly, never]

surreal ml export

The ML export command is used to export an existing machine learning model from SurrealDB.

Usage

surreal ml export [OPTIONS] --name <NAME> --version <VERSION> --namespace <NAMESPACE> --database <DATABASE> [FILE]

Arguments

Name	Default	Description
`[FILE]`	`-`	Path to the SurrealML file to write. Use a dash (`-`) to write into stdout.

Options

Name	Default	Environment variable	Description
`--name<NAME>` required	None	`SURREAL_NAME`	The name of the model to export.
`--version<VERSION>` required	None	`SURREAL_VERSION`	The version of the model to export.
`--endpoint, -e<ENDPOINT>`	`ws://localhost:8000`	None	Remote database server URL to connect to. Alias: `--conn`.
`--username, -u<USERNAME>`	None	`SURREAL_USER`	Database authentication username to use when connecting. Alias: `--user`.
`--password, -p<PASSWORD>`	None	`SURREAL_PASS`	Database authentication password to use when connecting. Alias: `--pass`.
`--token, -t<TOKEN>`	None	`SURREAL_TOKEN`	Authentication token in JWT format, used instead of a username and password.
`--auth-level<AUTH_LEVEL>`	`root`	`SURREAL_AUTH_LEVEL`	Level on which the authenticating user is defined. Possible values: `root`, `namespace` (`ns`), `database` (`db`).
`--namespace<NAMESPACE>` required	None	`SURREAL_NAMESPACE`	The namespace holding the model. Alias: `--ns`.
`--database<DATABASE>` required	None	`SURREAL_DATABASE`	The database holding the model. Alias: `--db`.
`--log, -l<LOG>`	`info`	`SURREAL_LOG`	The logging level for the command-line tool. Possible values: `none`, `full`, `error`, `warn`, `info`, `debug`, `trace`.

Example usage

To export a stored model to a local file, in a terminal run the surreal ml export command with the required arguments.

surreal ml export --conn http://localhost:8000 --user root --pass secret --ns main --db main --name my-surrealml-model --version 1.0.0 my-surrealml-model.surml

Using token-based authentication:

surreal ml export --conn http://localhost:8000 --token <token> --ns main --db main --name my-surrealml-model --version 1.0.0 my-surrealml-model.surml

Command help

To see the help information and usage instructions, in a terminal run the surreal ml export --help command without any further arguments. This command gives general information on the arguments, inputs, and additional options for the ml export command.

surreal ml export --help

The output of the above command:

Export a SurrealML model from an existing database

Usage: surreal ml export [OPTIONS] --name <NAME> --version <VERSION> --namespace <NAMESPACE> --database <DATABASE> [FILE]

Arguments:
  [FILE]  Path to the SurrealML file to export. Use dash - to write into stdout. [default: -]

Options:
      --name <NAME>              The name of the model [env: SURREAL_NAME=]
      --version <VERSION>        The version of the model [env: SURREAL_VERSION=]
  -e, --endpoint <ENDPOINT>      Remote database server url to connect to [default: ws://localhost:8000] [aliases: --conn]
  -u, --username <USERNAME>      Database authentication username to use when connecting [env: SURREAL_USER=] [aliases: --user]
  -p, --password <PASSWORD>      Database authentication password to use when connecting [env: SURREAL_PASS=] [aliases: --pass]
  -t, --token <TOKEN>            Authentication token in JWT format to use when connecting [env: SURREAL_TOKEN=]
      --auth-level <AUTH_LEVEL>  Level on which the authenticating user is defined [env: SURREAL_AUTH_LEVEL=] [default: root] [possible values: root, namespace, ns, database, db]
      --namespace <NAMESPACE>    The namespace selected for the operation [env: SURREAL_NAMESPACE=] [aliases: --ns]
      --database <DATABASE>      The database selected for the operation [env: SURREAL_DATABASE=] [aliases: --db]
  -h, --help                     Print help

Logging:
  -l, --log <LOG>                              The logging level for the command-line tool [env: SURREAL_LOG=] [default: info] [possible values: none, full, error, warn, info, debug, trace]
      --log-format <LOG_FORMAT>                The format for terminal log output [env: SURREAL_LOG_FORMAT=] [default: text] [possible values: text, json]
      --log-socket <LOG_SOCKET>                Send logs to the specified host:port [env: SURREAL_LOG_SOCKET=]
      --log-file-level <LOG_FILE_LEVEL>        Override the logging level for file output [env: SURREAL_LOG_FILE_LEVEL=] [possible values: none, full, error, warn, info, debug, trace]
      --log-otel-level <LOG_OTEL_LEVEL>        Override the logging level for OpenTelemetry output [env: SURREAL_LOG_OTEL_LEVEL=] [possible values: none, full, error, warn, info, debug, trace]
      --log-socket-level <LOG_SOCKET_LEVEL>    Override the logging level for unix socket output [env: SURREAL_LOG_SOCKET_LEVEL=] [possible values: none, full, error, warn, info, debug, trace]
      --log-socket-format <LOG_SOCKET_FORMAT>  The format for socket output [env: SURREAL_LOG_SOCKET_FORMAT=] [default: text] [possible values: text, json]
      --log-file-enabled                       Whether to enable log file output [env: SURREAL_LOG_FILE_ENABLED=]
      --log-file-path <LOG_FILE_PATH>          The directory where log files will be stored [env: SURREAL_LOG_FILE_PATH=] [default: logs]
      --log-file-name <LOG_FILE_NAME>          The name of the log file [env: SURREAL_LOG_FILE_NAME=] [default: surrealdb.log]
      --log-file-format <LOG_FILE_FORMAT>      The format for log file output [env: SURREAL_LOG_FILE_FORMAT=] [default: text] [possible values: text, json]
      --log-file-rotation <LOG_FILE_ROTATION>  The log file rotation interval [env: SURREAL_LOG_FILE_ROTATION=] [default: daily] [possible values: daily, hourly, never]

surreal ml import

The ML import command is used to import a new machine learning model into SurrealDB.

Usage

surreal ml import [OPTIONS] --namespace <NAMESPACE> --database <DATABASE> <FILE>

Arguments

Name	Description
`<FILE>` required	Path to the SurrealML file to import.

Options

Name	Default	Environment variable	Description
`--endpoint, -e<ENDPOINT>`	`ws://localhost:8000`	None	Remote database server URL to connect to. Alias: `--conn`.
`--username, -u<USERNAME>`	None	`SURREAL_USER`	Database authentication username to use when connecting. Alias: `--user`.
`--password, -p<PASSWORD>`	None	`SURREAL_PASS`	Database authentication password to use when connecting. Alias: `--pass`.
`--token, -t<TOKEN>`	None	`SURREAL_TOKEN`	Authentication token in JWT format, used instead of a username and password.
`--auth-level<AUTH_LEVEL>`	`root`	`SURREAL_AUTH_LEVEL`	Level on which the authenticating user is defined. Possible values: `root`, `namespace` (`ns`), `database` (`db`).
`--namespace<NAMESPACE>` required	None	`SURREAL_NAMESPACE`	The namespace to import the model into. Alias: `--ns`.
`--database<DATABASE>` required	None	`SURREAL_DATABASE`	The database to import the model into. Alias: `--db`.
`--log, -l<LOG>`	`info`	`SURREAL_LOG`	The logging level for the command-line tool. Possible values: `none`, `full`, `error`, `warn`, `info`, `debug`, `trace`.

Example usage

To import a model from a local file, in a terminal run the surreal ml import command with the required arguments.

surreal ml import --conn http://localhost:8000 --user root --pass secret \
  --ns main --db main my-surrealml-model.surml

Using token-based authentication:

surreal ml import --conn http://localhost:8000 --token <token> --ns main --db main my-surrealml-model.surml

Command help

To see the help information and usage instructions, in a terminal run the surreal ml import --help command without any further arguments. This command gives general information on the arguments, inputs, and additional options for the ml import command.

surreal ml import --help

The output of the above command:

Import a SurrealML model into an existing database

Usage: surreal ml import [OPTIONS] --namespace <NAMESPACE> --database <DATABASE> <FILE>

Arguments:
  <FILE>  Path to the SurrealML file to import

Options:
  -e, --endpoint <ENDPOINT>      Remote database server url to connect to [default: ws://localhost:8000] [aliases: --conn]
  -u, --username <USERNAME>      Database authentication username to use when connecting [env: SURREAL_USER=] [aliases: --user]
  -p, --password <PASSWORD>      Database authentication password to use when connecting [env: SURREAL_PASS=] [aliases: --pass]
  -t, --token <TOKEN>            Authentication token in JWT format to use when connecting [env: SURREAL_TOKEN=]
      --auth-level <AUTH_LEVEL>  Level on which the authenticating user is defined [env: SURREAL_AUTH_LEVEL=] [default: root] [possible values: root, namespace, ns, database, db]
      --namespace <NAMESPACE>    The namespace selected for the operation [env: SURREAL_NAMESPACE=] [aliases: --ns]
      --database <DATABASE>      The database selected for the operation [env: SURREAL_DATABASE=] [aliases: --db]
  -h, --help                     Print help

Logging:
  -l, --log <LOG>                              The logging level for the command-line tool [env: SURREAL_LOG=] [default: info] [possible values: none, full, error, warn, info, debug, trace]
      --log-format <LOG_FORMAT>                The format for terminal log output [env: SURREAL_LOG_FORMAT=] [default: text] [possible values: text, json]
      --log-socket <LOG_SOCKET>                Send logs to the specified host:port [env: SURREAL_LOG_SOCKET=]
      --log-file-level <LOG_FILE_LEVEL>        Override the logging level for file output [env: SURREAL_LOG_FILE_LEVEL=] [possible values: none, full, error, warn, info, debug, trace]
      --log-otel-level <LOG_OTEL_LEVEL>        Override the logging level for OpenTelemetry output [env: SURREAL_LOG_OTEL_LEVEL=] [possible values: none, full, error, warn, info, debug, trace]
      --log-socket-level <LOG_SOCKET_LEVEL>    Override the logging level for unix socket output [env: SURREAL_LOG_SOCKET_LEVEL=] [possible values: none, full, error, warn, info, debug, trace]
      --log-socket-format <LOG_SOCKET_FORMAT>  The format for socket output [env: SURREAL_LOG_SOCKET_FORMAT=] [default: text] [possible values: text, json]
      --log-file-enabled                       Whether to enable log file output [env: SURREAL_LOG_FILE_ENABLED=]
      --log-file-path <LOG_FILE_PATH>          The directory where log files will be stored [env: SURREAL_LOG_FILE_PATH=] [default: logs]
      --log-file-name <LOG_FILE_NAME>          The name of the log file [env: SURREAL_LOG_FILE_NAME=] [default: surrealdb.log]
      --log-file-format <LOG_FILE_FORMAT>      The format for log file output [env: SURREAL_LOG_FILE_FORMAT=] [default: text] [possible values: text, json]
      --log-file-rotation <LOG_FILE_ROTATION>  The log file rotation interval [env: SURREAL_LOG_FILE_ROTATION=] [default: daily] [possible values: daily, hourly, never]