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.
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, usingmyBranch
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 usingmyBranch
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.) Replacebeeff00d-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 replaceyour-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
: likeNORMAL
, 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 timestampfa32a50d5303a53826f65649277561f5c6772eba019e7f1e01a359becb764877
is a valid Nessie commit ID (hash)