Directories

The YDB database maintains an internal hierarchical structure of directories that can host database objects.

YDB CLI supports operations to change the directory structure and to access schema objects by their directory name.

Creating a directory

The scheme mkdir command creates the directories:

ydb [connection options] scheme mkdir <path>

where [connection options] are database connection options

In the path parameter, specify the relative path to the directory being created, from the root database directory. This command creates all the directories that didn't exist at the path when the command was called.

If the destination directory had already existed at the path, then the command execution will be completed successfully (result code 0) with a warning that no changes have been made:

Status: SUCCESS
Issues: 
<main>: Error: dst path fail checks, path: /<database>/<path>: path exist, request accepts it, 
pathId: [OwnerId: <some>, LocalPathId: <some>], path type: EPathTypeDir, path state: EPathStateNoChanges

The full path syntax starting with a / character is also supported. The full path must begin with the database location specified in the connection parameters or with which operations are allowed via the established connection to the cluster.

Examples:

  • Creating a directory at the database root

    ydb --profile db1 scheme mkdir dir1
    
  • Creating directories at the specified path from the database root

    ydb --profile db1 scheme mkdir dir1/dir2/dir3
    

Deleting a directory

The scheme rmdir command deletes a directory:

ydb [connection options] scheme rmdir <path>

where [connection options] are database connection options

In the path parameter, specify the relative path to the directory to be deleted. This directory must not contain objects (including tables and subdirectories), otherwise the command will fail with an error:

Status: SCHEME_ERROR
Issues: 
<main>: Error: path table fail checks, path: /<database>/<path>: path has children, request 
doesn't accept it, pathId: [OwnerId: <some>, LocalPathId: <some>], path type: 
EPathTypeDir, path state: EPathStateNoChanges, alive children: <count>

Using directories in other CLI commands

In all CLI commands to which the object name is passed by the parameter, it can be specified with a directory, for example, in scheme describe:

ydb --profile db1 scheme describe dir1/table_a

The scheme ls command supports passing the path to the directory as a parameter:

ydb --profile db1 scheme ls dir1/dir2

Using directories in YQL

Names of objects issued in YQL queries may contain a path to the object directory. This path will be concatenated with the path prefix from the TablePathPrefix pragma. If the pragma is omitted, the object name is resolved relative to the database root.

Implicit creation of directories during import

The data import command creates a directory tree mirroring the original imported catalog.