Nessie CLI¶

The Nessie CLI is an easy way to get started with Nessie. It supports multiple branch and tag management capabilities.

Nessie CLI is designed to be usable as an interactive REPL supporting auto-completion, highlighting where appropriate and has built-in help. Long outputs, like a commit log, are automatically paged like the Unix less command.

Nessie CLI

Installation¶

Nessie CLI is available as a standalone uber jar, or as a Docker image. See download options in the Nessie download page or in the releases page on GitHub.

Usage¶

Use CONNECT TO http://127.0.0.1:19120/iceberg to connect to a locally running Nessie instance with Iceberg REST. Use CONNECT TO http://127.0.0.1:19120/api/v2 for Nessie’s native REST API.

Use CONNECT TO https://app.dremio.cloud/repositories/<project-id>/api/v2 to connect to your Dremio cloud instance using Nessie’s native REST API.

See CONNECT statement below.

Command line options¶

Usage: nessie-cli.jar [-hHqV] [--no-up-to-date-check] [--non-ansi] [-j=<historyFile>] [[-K] [-E]
                      [-s=<scriptFile> | -c[=<commands>...] [-c[=<commands>...]]...]] [-u=<uri>
                      [--client-name=<clientName>] [-o[=<String=String>[,
                      <String=String>...]...]]... [-r=<initialReference>]]

The Nessie CLI
See https://projectnessie.org/nessie-latest/cli/ for documentation.

  -h, --help                Show this help message and exit.
  -H, --[no-]history        Allows disabling the command history file in the REPL.
                            Default is to save the command history.
  -j, --history-file=<historyFile>
                            Specify an alternative history file for the REPL.
                              Default: ~/.nessie/nessie-cli.history
      --no-up-to-date-check Optionally disable the up-to-date check.
                            Only effective if --quiet is not specified.
      --non-ansi            Allows disabling the (default) ANSI mode. Disabling ANSI support can be
                              useful in non-interactive scripts.
  -q, --quiet               Quiet option - omit the welcome and exit output.
  -V, --version             Print version information and exit.

Statements to execute before or without running the REPL
========================================================

  -c, --command[=<commands>...]
                            Nessie CLI commands to run. Each value represents one command.
                            The process will exit once all specified commands have been executed.
                              To keep the REPL running in case of errors, specify the
                              --keep-running option.
  -E, --continue-on-error   When running commands via the --command or --run-script option the
                              process will stop/exit when a command could not be parsed or ran into
                              an error.
                            Specifying this option lets the REPL continue executing the remaining
                              commands after parse or runtime errors.
  -K, --keep-running        When running commands via the --command or --run-script option the
                              process will exit once the commands have been executed.
                            To keep the REPL running, specify this option.See the
                              --continue-on-error option.
  -s, --run-script=<scriptFile>
                            Run the commands in the Nessie CLI script referenced by this option.
                            Possible values are either a file path or use the minus character ('-')
                              to read the script from stdin.

Connect options
===============

      --client-name=<clientName>
                            Name of the client implementation to use, defaults to HTTP suitable for
                              Nessie REST API.
                            See https://projectnessie.org/nessie-latest/client_config/ for the
                              'nessie.client-builder-name' option.
  -o, --client-option[=<String=String>[,<String=String>...]...]
                            Parameters to configure the REST client.
                            See https://projectnessie.org/nessie-latest/client_config/
  -r, --initial-reference=<initialReference>
                            Name of the Nessie reference to use.
  -u, --uri=<uri>           REST API endpoint URI to connect to.
                            See 'HELP CONNECT' in the REPL.

REPL Commands¶

The following syntax descriptions illustrate how commands are used and the order of the clauses.

Info

CODE style means the term is a keyword.

BoldTerms mean variable input, see Descripton of Command Parts below

Square brackets [ ] mean that the contents are optional (0 or 1 occurrence).

Curly brackets { } mean that the contents can be repeated 0 or more times.

`CONNECT`¶

CONNECT TO Uri
[ ON ReferenceName ]
[ USING ParamKey = Value { AND ParamKey = Value } ]

Connect to a Nessie repository using the Nessie REST API base URI specified via Uri.

When using Nessie with Iceberg REST, it is recommended to use the Iceberg REST base URI instead of the Nessie REST base URI.

Nessie client options can be specified using the ParamKey = Value pairs, see https://projectnessie.org/nessie-latest/client_config/,

If the Nessie CLI is already connected to a Nessie repository, that connection will be closed.

Tip: If your connect string contains sensitive information, like a password or an access token, put a space before the CONNECT statement, which instructs the Nessie CLI to not record the statement in the history file.

Examples:

Local Nessie with Iceberg REST, using the default branch: CONNECT TO http://127.0.0.1:19120/iceberg/ for a locally running Nessie instance with Iceberg REST (on your machine) without authentication enabled.
Nessie with Iceberg REST, using another branch: CONNECT TO http://127.0.0.1:19120/iceberg ON myBranch for a locally running Nessie instance with Iceberg REST (on your machine) without authentication enabled, using myBranch as the initial reference name. Alternatively, you can add the initial reference name to the URI like this: CONNECT TO http://127.0.0.1:19120/iceberg/myBranch.
Local Nessie: CONNECT TO http://127.0.0.1:19120/api/v2 for a locally running Nessie instance (on your machine) without authentication enabled.
Local Nessie: CONNECT TO http://127.0.0.1:19120/api/v2 ON myBranch for a locally running Nessie instance (on your machine) without authentication enabled, but using myBranch as the initial reference.
Dremio Cloud: CONNECT to https://app.dremio.cloud/repositories/beeff00d-1122-1234-4242-feedcafebabe/api/v2 USING "nessie.authentication.type" = BEARER AND "nessie.authentication.token" = "your-personal-bearer-token" to connect to Dremio Cloud. (The statement must not contain line breaks.) Replace beeff00d-1122-1234-4242-feedcafebabe with your project ID. The complete endpoint URI of your Dremio Cloud catalog can be found in the catalog settings as Catalog Endpoint under General Information. Also replace your-personal-bearer-token with a personal token, which can be created in your account settings under Personal Access Tokens. Do never share a personal access token!

When using “interactive” OAuth2 device-code or authorization-code flows, you can abort the login by pressing Ctrl-C.

`CREATE BRANCH` / `TAG`¶

CREATE ReferenceType
[ IF NOT EXISTS ]
ReferenceName
[ FROM ExistingReference ]
[ AT [ TIMESTAMP | COMMIT ] TimestampOrCommit ]

Creates a new Nessie branch or tag using the name specified using the ReferenceName parameter. The reference type is specified using the ReferenceType parameter.

By default, the new branch or tag is created from the latest commit on the current reference of the Nessie CLI (see USE statement). Another source reference name can use specified using the FROM clause. The optional AT clause allows specifying a different commit ID (hash) to create the new reference from.

This command will fail, if a references with the name ReferenceName already exists, unless the optional IF NOT EXISTS is specified.

`CREATE NAMESPACE`¶

CREATE NAMESPACE ContentKey
[ ON [ ReferenceType ] ExistingReference ]
[ SET ParamKey = Value { AND ParamKey = Value } ]

Creates a new namespace in the current branch, or in the branch specified using the IN clause.

Namespace properties can be set using the key/value pairs in the SET clause.

`DROP BRANCH` / `TAG`¶

DROP ReferenceType [ IF EXISTS ] ExistingReference

Drops a new Nessie branch or tag using the name specified using the ReferenceName parameter. The reference type is specified using the ReferenceType parameter.

This command will fail, if a references with the name ReferenceName does not exist, unless the optional IF EXISTS is specified.

`DROP TABLE` / `VIEW` / `NAMESPACE`¶

DROP ContentKind ContentKey
[ ON [ ReferenceType ] ExistingReference ]

Drops a table or view in the current branch, or in the branch specified using the IN clause.

Note that dropping namespaces must be performed using the DROP NAMESPACE command.

`ASSIGN BRANCH` / `TAG`¶

ASSIGN ReferenceType
[ ExistingReference ]
[ TO ExistingReference [ AT [ TIMESTAMP | COMMIT ] TimestampOrCommit ] ]

Assigns a Nessie branch or tag using the name specified using the ReferenceName parameter to another commit. The reference type is specified using the ReferenceType parameter.

By default, the branch or tag is updated to the latest commit on the current reference of the Nessie CLI (see USE statement). Another target reference name can use specified using the TO clause. The optional AT clause allows specifying a different commit ID (hash) to assign the reference to.

`ALTER NAMESPACE`¶

ALTER NAMESPACE ContentKey
[ ON [ ReferenceType ] ExistingReference ]
[ SET ParamKey = Value { AND ParamKey = Value } ]
[ REMOVE ParamKey { AND ParamKey } ]

Updates a namespace in the current branch, or in the branch specified using the IN clause.

New namespace properties can be set using the key/value pairs in the SET clause.

Existing namespace properties can be updated using the key/value pairs in the SET clause.

Existing namespace properties can be removed using the keys specified in the REMOVE clause.

`LIST CONTENTS`¶

LIST CONTENTS
[ ON [ ReferenceType ] ExistingReference ]
[ AT [ TIMESTAMP | COMMIT ] TimestampOrCommit ]
[ FILTER Value
| [ STARTING WITH Value ] [ CONTAINING Value ]
]

Lists all tables, views and namespaces either in the current reference of the Nessie CLI, or in the branch or tab specified using the IN clause. By default entities on the latest commit of the branch or tag will be listed, which can be overridden using the AT clause.

An optional CEL-filter can be specified, which is evaluated on the server side.

The optional STARTING WITH clause starts the output at the content-key with the given value.

The optional CONTAINING clause only outputs entities with a content-key that contain the given value.

`LIST REFERENCES`¶

LIST REFERENCES
[ FILTER Value
| [ STARTING WITH Value ] [ CONTAINING Value ]
]

Lists all named references.

An optional CEL-filter can be specified, which is evaluated on the server side.

The optional STARTING WITH clause starts the output at the content-key with the given value.

The optional CONTAINING clause only outputs entities with a content-key that contain the given value.

`MERGE BRANCH`¶

MERGE
[ DRY ]
[ ReferenceType ]
ExistingReference
[ AT [ TIMESTAMP | COMMIT ] TimestampOrCommit ]
[ INTO ExistingReference ]
[ BEHAVIOR MergeBehaviorKind ]
[ BEHAVIORS ContentKey = MergeBehaviorKind { AND ContentKey = MergeBehaviorKind } ]

Merges a branch or tag into another branch, supporting manual conflict resolution.

The optional DRY keyword defines that Nessie shall simulate a merge operation. This is useful to check whether a merge operation would succeed.

Specifying the name of the “from” reference is mandatory. By default, the latest commit of the “from” branch or tag will be merged, which can be overridden using the AT clause.

By default, MERGE uses the CLI’s current reference as the target branch. The INTO clause can be used to specify another target branch.

Nessie merge operations currently support three different merge behaviors:

NORMAL: a merge succeeds, if the content does not have a conflicting change in the target branch.
FORCE: a merge always succeeds, the content from the “from” reference will be applied onto the target branch.
DROP: like NORMAL, but does not cause a conflict, so does not fail the whole merge operation.

The merge behavior for all contents defaults to NORMAL and can be changed using the BEHAVIOR clause.

Specific merge behaviors can be specified using the BEHAVIORS clause for individual content keys.

`REVERT CONTENT`¶

REVERT CONTENT
[ DRY ]
OF ContentKey
{ AND ContentKey }
[ ON [ ReferenceType ] ExistingReference ]
TO STATE
( ON [ ReferenceType ] ExistingReference [ AT [ TIMESTAMP | COMMIT ] TimestampOrCommit ]
| AT [ TIMESTAMP | COMMIT ] TimestampOrCommit
)
[ ALLOW DELETES ]

Creates a new commit in Nessie to set the state of the given content-keys to the same state as those content keys existed on the TO STATE reference.

This command is for example useful when another system has created a Nessie commit but the referenced Iceberg metadata object was not written.

It is recommended to use the DRY keyword to investigate the changes before actually committing those to Nessie.

Contents that exist on the TO STATE are updated in the new Nessie commit to that state. Contents that do not exist on the TO STATE are deleted only if the ALLOW DELETES clause is specified, otherwise the command will fail.

Note that this command will always create a new commit, even if the actual contents at the “tip” of the target branch and the TO STATE are equal.

`SHOW LOG`¶

SHOW LOG
[ [ ON [ ReferenceType ] ] ExistingReference ]
[ AT [ TIMESTAMP | COMMIT ] TimestampOrCommit ]
[ LIMIT PositiveInt ]

Shows the Nessie commit log.

By default, the commit log fetched for the current reference of the Nessie CLI, or in the branch or tab specified using the IN clause. By default entities on the latest commit of the branch or tag will be listed, which can be overridden using the AT clause.

The output can be limited using the LIMIT clause. It is safe to omit the LIMIT clause for ANSI terminals, because the commit log will be safely paged with neither overloading the Nessie CLI or Nessie server.

`SHOW TABLE` / `VIEW` / `NAMESPACE`¶

SHOW ContentKind
[ ON [ ReferenceType ] ExistingReference ]
[ AT [ TIMESTAMP | COMMIT ] TimestampOrCommit ]
ContentKey

Shows the content of a table, view or namespaces that is stored in Nessie.

By default, the content will be looked up in the current reference of the Nessie CLI, or in the branch or tab specified using the IN clause. By default entities on the latest commit of the branch or tag will be listed, which can be overridden using the AT clause.

`SHOW REFERENCE`¶

SHOW REFERENCE
[ ExistingReference ]
[ AT [ TIMESTAMP | COMMIT ] TimestampOrCommit ]

Shows information about the current or given reference.

If no reference is specified, information about the current reference of the Nessie CLI is shown, otherwise information about the given reference. By default, entities information of latest commit of the branch or tag will be shown, which can be overridden using the AT clause.

`USE`¶

USE
( ReferenceType
| REFERENCE
)
ExistingReference
[ AT [ TIMESTAMP | COMMIT ] TimestampOrCommit ]

Changes the current reference in the Nessie CLI to the branch or tag name in ExistingReference.

`HELP`¶

HELP
[ USE
| CONNECT
| CREATE [ ( BRANCH | TAG | NAMESPACE ) ]
| ALTER [ NAMESPACE ]
| DROP [ BRANCH | TAG | NAMESPACE | TABLE | VIEW ]
| LIST [ CONTENTS | REFERENCES ]
| SHOW [ LOG | TABLE | VIEW | NAMESPACE | REFERENCE ]
| ASSIGN [ BRANCH | TAG ]
| MERGE
| REVERT
| HELP
| EXIT
| LICENSE
]

Shows available commands or detailed information about a specific command.

HELP shows all available command.

HELP plus another command shows information about that specific command. Some commands require multiple keywords, for example HELP CREATE and HELP CREATE BRANCH or HELP CREATE NAMESPACE.

`EXIT`¶

EXIT

Exits the Nessie CLI.

Command parts¶

ReferenceType¶

BRANCH | TAG

ContentKind¶

TABLE | VIEW | NAMESPACE

ExistingReference¶

Name of an existing reference in Nessie.

ReferenceName¶

Nessie reference name.

TimestampOrCommit¶

Either a Nessie commit ID (hash) or a timestamp in ISO format. Examples:

2024-04-26T10:31:05.277650575Z is a valid ISO timestamp
fa32a50d5303a53826f65649277561f5c6772eba019e7f1e01a359becb764877 is a valid Nessie commit ID (hash)

Nessie CLI¶

Installation¶

Usage¶

Command line options¶

REPL Commands¶

CONNECT¶

CREATE BRANCH / TAG¶

CREATE NAMESPACE¶

DROP BRANCH / TAG¶

DROP TABLE / VIEW / NAMESPACE¶

ASSIGN BRANCH / TAG¶

ALTER NAMESPACE¶

LIST CONTENTS¶

LIST REFERENCES¶

MERGE BRANCH¶

REVERT CONTENT¶

SHOW LOG¶

SHOW TABLE / VIEW / NAMESPACE¶

SHOW REFERENCE¶

USE¶

HELP¶

EXIT¶