Apache Kudu Command Line Tools Reference

Command Details

cluster: Operate on a Kudu cluster


ksck: Check the health of a Kudu cluster 

By default, ksck checks that master and tablet server processes are running, and that table metadata is consistent. Use the 'checksum' flag to check that tablet data is consistent (also see the 'tables' and 'tablets' flags). Use the 'checksum_snapshot' along with 'checksum' if the table or tablets are actively receiving inserts or updates.
Usage:
kudu cluster ksck <master_addresses> [-checksum_cache_blocks] [-checksum_scan] [-checksum_scan_concurrency=<concurrency>] [-nochecksum_snapshot] [-color=<color>] [-tables=<tables>] [-tablets=<tablets>]
Arguments:

Name Description Type Default

master_addresses

Comma-separated list of Kudu Master addresses where each address is of form 'hostname:port'

string

none

checksum_cache_blocks (optional)

Should the checksum scanners cache the read blocks

bool

false

checksum_scan (optional)

Perform a checksum scan on data in the cluster.

bool

false

checksum_scan_concurrency (optional)

Number of concurrent checksum scans to execute per tablet server.

int32

4

checksum_snapshot (optional)

Should the checksum scanner use a snapshot scan

bool

true

color (optional)

Specifies whether output should be colorized. The default value 'auto' colorizes output if the output is a terminal. The other valid values are 'always' or 'never'.

string

auto

tables (optional)

Tables to check (comma-separated list of names). If not specified, checks all tables.

string

none

tablets (optional)

Tablets to check (comma-separated list of IDs) If not specified, checks all tablets.

string

none


fs: Operate on a local Kudu filesystem


format: Format a new Kudu filesystem 

Usage:
kudu fs format [-fs_wal_dir=<dir>] [-fs_data_dirs=<dirs>] [-uuid=<uuid>]
Arguments:

Name Description Type Default

fs_wal_dir (optional)

Directory with write-ahead logs. If this is not specified, the program will not start. May be the same as fs_data_dirs

string

none

fs_data_dirs (optional)

Comma-separated list of directories with data blocks. If this is not specified, fs_wal_dir will be used as the sole data block directory.

string

none

uuid (optional)

The uuid to use in the filesystem. If not provided, one is generated

string

none


dump: Dump a Kudu filesystem


cfile: Dump the contents of a CFile (column file) 

Usage:
kudu fs dump cfile <block_id> [-fs_wal_dir=<dir>] [-fs_data_dirs=<dirs>] [-noprint_meta] [-noprint_rows]
Arguments:

Name Description Type Default

block_id

block identifier

string

none

fs_wal_dir (optional)

Directory with write-ahead logs. If this is not specified, the program will not start. May be the same as fs_data_dirs

string

none

fs_data_dirs (optional)

Comma-separated list of directories with data blocks. If this is not specified, fs_wal_dir will be used as the sole data block directory.

string

none

print_meta (optional)

Include metadata in output

bool

true

print_rows (optional)

Print each row in the CFile

bool

true


tree: Dump the tree of a Kudu filesystem 

Usage:
kudu fs dump tree [-fs_wal_dir=<dir>] [-fs_data_dirs=<dirs>]
Arguments:

Name Description Type Default

fs_wal_dir (optional)

Directory with write-ahead logs. If this is not specified, the program will not start. May be the same as fs_data_dirs

string

none

fs_data_dirs (optional)

Comma-separated list of directories with data blocks. If this is not specified, fs_wal_dir will be used as the sole data block directory.

string

none


uuid: Dump the UUID of a Kudu filesystem 

Usage:
kudu fs dump uuid [-fs_wal_dir=<dir>] [-fs_data_dirs=<dirs>]
Arguments:

Name Description Type Default

fs_wal_dir (optional)

Directory with write-ahead logs. If this is not specified, the program will not start. May be the same as fs_data_dirs

string

none

fs_data_dirs (optional)

Comma-separated list of directories with data blocks. If this is not specified, fs_wal_dir will be used as the sole data block directory.

string

none


local_replica: Operate on local tablet replicas via the local filesystem


copy_from_remote: Copy a tablet replica from a remote server 

Usage:
kudu local_replica copy_from_remote <tablet_id> <source> [-fs_wal_dir=<dir>] [-fs_data_dirs=<dirs>]
Arguments:

Name Description Type Default

tablet_id

Tablet Identifier

string

none

source

Source RPC address of form hostname:port

string

none

fs_wal_dir (optional)

Directory with write-ahead logs. If this is not specified, the program will not start. May be the same as fs_data_dirs

string

none

fs_data_dirs (optional)

Comma-separated list of directories with data blocks. If this is not specified, fs_wal_dir will be used as the sole data block directory.

string

none


delete: Delete a tablet replica from the local filesystem. By default, leaves a tombstone record. 

Usage:
kudu local_replica delete <tablet_id> [-fs_wal_dir=<dir>] [-fs_data_dirs=<dirs>] [-clean_unsafe]
Arguments:

Name Description Type Default

tablet_id

Tablet Identifier

string

none

fs_wal_dir (optional)

Directory with write-ahead logs. If this is not specified, the program will not start. May be the same as fs_data_dirs

string

none

fs_data_dirs (optional)

Comma-separated list of directories with data blocks. If this is not specified, fs_wal_dir will be used as the sole data block directory.

string

none

clean_unsafe (optional)

Delete the local replica completely, not leaving a tombstone. This is not guaranteed to be safe because it also removes the consensus metadata (including Raft voting record) for the specified tablet, which violates the Raft vote durability requirements.

bool

false


list: Show list of tablet replicas in the local filesystem 

Usage:
kudu local_replica list [-fs_wal_dir=<dir>] [-fs_data_dirs=<dirs>] [-list_detail]
Arguments:

Name Description Type Default

fs_wal_dir (optional)

Directory with write-ahead logs. If this is not specified, the program will not start. May be the same as fs_data_dirs

string

none

fs_data_dirs (optional)

Comma-separated list of directories with data blocks. If this is not specified, fs_wal_dir will be used as the sole data block directory.

string

none

list_detail (optional)

Print partition info for the local replicas

bool

false


cmeta: Operate on a local tablet replica’s consensus metadata file


print_replica_uuids: Print all tablet replica peer UUIDs found in a tablet’s Raft configuration 

Usage:
kudu local_replica cmeta print_replica_uuids <tablet_id> [-fs_wal_dir=<dir>] [-fs_data_dirs=<dirs>]
Arguments:

Name Description Type Default

tablet_id

Tablet Identifier

string

none

fs_wal_dir (optional)

Directory with write-ahead logs. If this is not specified, the program will not start. May be the same as fs_data_dirs

string

none

fs_data_dirs (optional)

Comma-separated list of directories with data blocks. If this is not specified, fs_wal_dir will be used as the sole data block directory.

string

none


rewrite_raft_config: Rewrite a tablet replica’s Raft configuration 

Usage:
kudu local_replica cmeta rewrite_raft_config <tablet_id> <peers>…​ [-fs_wal_dir=<dir>] [-fs_data_dirs=<dirs>]
Arguments:

Name Description Type Default

tablet_id

Tablet Identifier

string

none

peers…​

List of peers where each peer is of form 'uuid:hostname:port'

string

none

fs_wal_dir (optional)

Directory with write-ahead logs. If this is not specified, the program will not start. May be the same as fs_data_dirs

string

none

fs_data_dirs (optional)

Comma-separated list of directories with data blocks. If this is not specified, fs_wal_dir will be used as the sole data block directory.

string

none


dump: Dump a Kudu filesystem


block_ids: Dump the IDs of all blocks belonging to a local replica 

Usage:
kudu local_replica dump block_ids <tablet_id> [-fs_wal_dir=<dir>] [-fs_data_dirs=<dirs>]
Arguments:

Name Description Type Default

tablet_id

Tablet Identifier

string

none

fs_wal_dir (optional)

Directory with write-ahead logs. If this is not specified, the program will not start. May be the same as fs_data_dirs

string

none

fs_data_dirs (optional)

Comma-separated list of directories with data blocks. If this is not specified, fs_wal_dir will be used as the sole data block directory.

string

none


meta: Dump the metadata of a local replica 

Usage:
kudu local_replica dump meta <tablet_id> [-fs_wal_dir=<dir>] [-fs_data_dirs=<dirs>]
Arguments:

Name Description Type Default

tablet_id

Tablet Identifier

string

none

fs_wal_dir (optional)

Directory with write-ahead logs. If this is not specified, the program will not start. May be the same as fs_data_dirs

string

none

fs_data_dirs (optional)

Comma-separated list of directories with data blocks. If this is not specified, fs_wal_dir will be used as the sole data block directory.

string

none


rowset: Dump the rowset contents of a local replica 

Usage:
kudu local_replica dump rowset <tablet_id> [-dump_data] [-fs_wal_dir=<dir>] [-fs_data_dirs=<dirs>] [-metadata_only] [-nrows=<nrows>] [-rowset_index=<index>]
Arguments:

Name Description Type Default

tablet_id

Tablet Identifier

string

none

dump_data (optional)

Dump the data for each column in the rowset.

bool

false

fs_wal_dir (optional)

Directory with write-ahead logs. If this is not specified, the program will not start. May be the same as fs_data_dirs

string

none

fs_data_dirs (optional)

Comma-separated list of directories with data blocks. If this is not specified, fs_wal_dir will be used as the sole data block directory.

string

none

metadata_only (optional)

Only dump the block metadata when printing blocks.

bool

false

nrows (optional)

Number of rows to dump

int64

0

rowset_index (optional)

Index of the rowset in local replica, default value(-1) will dump all the rowsets of the local replica

int64

-1


wals: Dump all WAL (write-ahead log) segments of a local replica 

Usage:
kudu local_replica dump wals <tablet_id> [-fs_wal_dir=<dir>] [-fs_data_dirs=<dirs>] [-print_entries=<entries>] [-noprint_meta] [-truncate_data=<data>]
Arguments:

Name Description Type Default

tablet_id

Tablet Identifier

string

none

fs_wal_dir (optional)

Directory with write-ahead logs. If this is not specified, the program will not start. May be the same as fs_data_dirs

string

none

fs_data_dirs (optional)

Comma-separated list of directories with data blocks. If this is not specified, fs_wal_dir will be used as the sole data block directory.

string

none

print_entries (optional)

How to print entries: false|0|no = don’t print true|1|yes|decoded = print them decoded pb = print the raw protobuf id = print only their ids

string

decoded

print_meta (optional)

Include metadata in output

bool

true

truncate_data (optional)

Truncate the data fields to the given number of bytes before printing. Set to 0 to disable

int32

100


master: Operate on a Kudu Master


set_flag: Change a gflag value on a Kudu Master 

Usage:
kudu master set_flag <master_address> <flag> <value> [-force]
Arguments:

Name Description Type Default

master_address

Address of a Kudu Master of form 'hostname:port'. Port may be omitted if the Master is bound to the default port.

string

none

flag

Name of the gflag

string

none

value

New value for the gflag

string

none

force (optional)

If true, allows the set_flag command to set a flag which is not explicitly marked as runtime-settable. Such flag changes may be simply ignored on the server, or may cause the server to crash.

bool

false


status: Get the status of a Kudu Master 

Usage:
kudu master status <master_address>
Arguments:

Name Description Type Default

master_address

Address of a Kudu Master of form 'hostname:port'. Port may be omitted if the Master is bound to the default port.

string

none


timestamp: Get the current timestamp of a Kudu Master 

Usage:
kudu master timestamp <master_address>
Arguments:

Name Description Type Default

master_address

Address of a Kudu Master of form 'hostname:port'. Port may be omitted if the Master is bound to the default port.

string

none


pbc: Operate on PBC (protobuf container) files


dump: Dump a PBC (protobuf container) file 

Usage:
kudu pbc dump <path> [-oneline]
Arguments:

Name Description Type Default

path

path to PBC file

string

none

oneline (optional)

print each protobuf on a single line

bool

false


remote_replica: Operate on remote tablet replicas on a Kudu Tablet Server


check: Check if all tablet replicas on a Kudu Tablet Server are running 

Usage:
kudu remote_replica check <tserver_address>
Arguments:

Name Description Type Default

tserver_address

Address of a Kudu Tablet Server of form 'hostname:port'. Port may be omitted if the Tablet Server is bound to the default port.

string

none


copy: Copy a tablet replica from one Kudu Tablet Server to another 

Usage:
kudu remote_replica copy <tablet_id> <src_address> <dst_address> [-force_copy]
Arguments:

Name Description Type Default

tablet_id

Tablet Identifier

string

none

src_address

Address of a Kudu Tablet Server of form 'hostname:port'. Port may be omitted if the Tablet Server is bound to the default port.

string

none

dst_address

Address of a Kudu Tablet Server of form 'hostname:port'. Port may be omitted if the Tablet Server is bound to the default port.

string

none

force_copy (optional)

Force the copy when the destination tablet server has this replica

bool

false


delete: Delete a tablet replica from a Kudu Tablet Server 

Usage:
kudu remote_replica delete <tserver_address> <tablet_id> <reason>
Arguments:

Name Description Type Default

tserver_address

Address of a Kudu Tablet Server of form 'hostname:port'. Port may be omitted if the Tablet Server is bound to the default port.

string

none

tablet_id

Tablet Identifier

string

none

reason

Reason for deleting the replica

string

none


dump: Dump the data of a tablet replica on a Kudu Tablet Server 

Usage:
kudu remote_replica dump <tserver_address> <tablet_id>
Arguments:

Name Description Type Default

tserver_address

Address of a Kudu Tablet Server of form 'hostname:port'. Port may be omitted if the Tablet Server is bound to the default port.

string

none

tablet_id

Tablet Identifier

string

none


list: List all tablet replicas on a Kudu Tablet Server 

Usage:
kudu remote_replica list <tserver_address>
Arguments:

Name Description Type Default

tserver_address

Address of a Kudu Tablet Server of form 'hostname:port'. Port may be omitted if the Tablet Server is bound to the default port.

string

none


table: Operate on Kudu tables


delete: Delete a table 

Usage:
kudu table delete <master_addresses> <table_name>
Arguments:

Name Description Type Default

master_addresses

Comma-separated list of Kudu Master addresses where each address is of form 'hostname:port'

string

none

table_name

Name of the table to delete

string

none


list: List all tables 

Usage:
kudu table list <master_addresses> [-list_tablets]
Arguments:

Name Description Type Default

master_addresses

Comma-separated list of Kudu Master addresses where each address is of form 'hostname:port'

string

none

list_tablets (optional)

Include tablet and replica UUIDs in the output

bool

false


tablet: Operate on remote Kudu tablets


leader_step_down: Force the tablet’s leader replica to step down 

Usage:
kudu tablet leader_step_down <master_addresses> <tablet_id>
Arguments:

Name Description Type Default

master_addresses

Comma-separated list of Kudu Master addresses where each address is of form 'hostname:port'

string

none

tablet_id

Tablet Identifier

string

none


change_config: Change a tablet’s Raft configuration


add_replica: Add a new replica to a tablet’s Raft configuration 

Usage:
kudu tablet change_config add_replica <master_addresses> <tablet_id> <replica_uuid> <replica_type>
Arguments:

Name Description Type Default

master_addresses

Comma-separated list of Kudu Master addresses where each address is of form 'hostname:port'

string

none

tablet_id

Tablet Identifier

string

none

replica_uuid

New replica’s UUID

string

none

replica_type

New replica’s type. Must be VOTER or NON-VOTER.

string

none


change_replica_type: Change the type of an existing replica in a tablet’s Raft configuration 

Usage:
kudu tablet change_config change_replica_type <master_addresses> <tablet_id> <replica_uuid> <replica_type>
Arguments:

Name Description Type Default

master_addresses

Comma-separated list of Kudu Master addresses where each address is of form 'hostname:port'

string

none

tablet_id

Tablet Identifier

string

none

replica_uuid

Existing replica’s UUID

string

none

replica_type

Existing replica’s new type. Must be VOTER or NON-VOTER.

string

none


remove_replica: Remove an existing replica from a tablet’s Raft configuration 

Usage:
kudu tablet change_config remove_replica <master_addresses> <tablet_id> <replica_uuid>
Arguments:

Name Description Type Default

master_addresses

Comma-separated list of Kudu Master addresses where each address is of form 'hostname:port'

string

none

tablet_id

Tablet Identifier

string

none

replica_uuid

Existing replica’s UUID

string

none


test: Run various tests against a Kudu cluster


loadgen: Run load generation test with optional scan afterwards 

Run load generation tool which inserts auto-generated data into already existing or auto-created table as fast as possible. If requested, also run scan over the inserted rows to check whether the actual count or inserted rows matches the expected one.
Usage:
kudu test loadgen <master_addresses> [-buffer_flush_watermark_pct=<pct>] [-buffer_size_bytes=<bytes>] [-buffers_num=<num>] [-flush_per_n_rows=<rows>] [-keep_auto_table] [-num_rows_per_thread=<thread>] [-num_threads=<threads>] [-run_scan] [-seq_start=<start>] [-show_first_n_errors=<errors>] [-string_fixed=<fixed>] [-string_len=<len>] [-table_name=<name>] [-table_num_buckets=<buckets>] [-table_num_replicas=<replicas>] [-use_random]
Arguments:

Name Description Type Default

master_addresses

Comma-separated list of master addresses to run against. Addresses are in 'hostname:port' form where port may be omitted if a master server listens at the default port.

string

none

buffer_flush_watermark_pct (optional)

Mutation buffer flush watermark, in percentage of total size.

double

0.5

buffer_size_bytes (optional)

Size of the mutation buffer, per session (bytes).

int32

4194304

buffers_num (optional)

Number of mutation buffers per session.

int32

2

flush_per_n_rows (optional)

Perform async flush per given number of rows added. Setting to non-zero implicitly turns on manual flush mode.

int32

0

keep_auto_table (optional)

If using the auto-generated table, enabling this option retains the table populated with the data after the test finishes. By default, the auto-generated table is dropped after sucessfully finishing the test. NOTE: this parameter has no effect if using already existing table (see the '--table_name' flag): the existing tables nor their data are never dropped/deleted.

bool

false

num_rows_per_thread (optional)

Number of rows each thread generates and inserts; 0 means unlimited. All rows generated by a thread are inserted in the context of the same session.

uint64

1000

num_threads (optional)

Number of generator threads to run. Each thread runs its own KuduSession.

int32

2

run_scan (optional)

Whether to run post-insertion scan to verify that the count of the inserted rows matches the expected number. If enabled, the scan is run only if no errors were encountered while inserting the generated rows.

bool

false

seq_start (optional)

Initial value for the generator in sequential mode. This is useful when running multiple times against already existing table: for every next run, set this flag to (num_threads * num_rows_per_thread * column_num + seq_start).

uint64

0

show_first_n_errors (optional)

Output detailed information on the specified number of first n errors (if any).

int32

0

string_fixed (optional)

Pre-defined string to write into binary and string columns. Client generates more data per second using pre-defined string compared with auto-generated strings of the same length if run with the same CPU/memory configuration. If left empty, then auto-generated strings of length specified by the '--string_len' parameter are used instead.

string

none

string_len (optional)

Length of strings to put into string and binary columns. This parameter is not in effect if '--string_fixed' is specified.

int32

32

table_name (optional)

Name of an existing table to use for the test. The test will determine the structure of the table schema and populate it with data accordingly. If left empty, the test automatically creates a table of pre-defined columnar structure with unique name and uses it to insert auto-generated data. The auto-created table is dropped upon successful completion of the test if not overridden by the '--keep_auto_table' flag. If running the test against an already existing table, it’s highly recommended to use a dedicated table created just for testing purposes: the existing table nor its data is never dropped/deleted.

string

none

table_num_buckets (optional)

The number of buckets to create when this tool creates a new table.

int32

8

table_num_replicas (optional)

The number of replicas for the auto-created table; 0 means 'use server-side default'.

int32

1

use_random (optional)

Whether to use random numbers instead of sequential ones. In case of using random numbers collisions are possible over the data for columns with unique constraint (e.g. primary key).

bool

false


tserver: Operate on a Kudu Tablet Server


set_flag: Change a gflag value on a Kudu Tablet Server 

Usage:
kudu tserver set_flag <tserver_address> <flag> <value> [-force]
Arguments:

Name Description Type Default

tserver_address

Address of a Kudu Tablet Server of form 'hostname:port'. Port may be omitted if the Tablet Server is bound to the default port.

string

none

flag

Name of the gflag

string

none

value

New value for the gflag

string

none

force (optional)

If true, allows the set_flag command to set a flag which is not explicitly marked as runtime-settable. Such flag changes may be simply ignored on the server, or may cause the server to crash.

bool

false


status: Get the status of a Kudu Tablet Server 

Usage:
kudu tserver status <tserver_address>
Arguments:

Name Description Type Default

tserver_address

Address of a Kudu Tablet Server of form 'hostname:port'. Port may be omitted if the Tablet Server is bound to the default port.

string

none


timestamp: Get the current timestamp of a Kudu Tablet Server 

Usage:
kudu tserver timestamp <tserver_address>
Arguments:

Name Description Type Default

tserver_address

Address of a Kudu Tablet Server of form 'hostname:port'. Port may be omitted if the Tablet Server is bound to the default port.

string

none


wal: Operate on WAL (write-ahead log) files


dump: Dump a WAL (write-ahead log) file 

Usage:
kudu wal dump <path> [-print_entries=<entries>] [-noprint_meta] [-truncate_data=<data>]
Arguments:

Name Description Type Default

path

path to WAL file

string

none

print_entries (optional)

How to print entries: false|0|no = don’t print true|1|yes|decoded = print them decoded pb = print the raw protobuf id = print only their ids

string

decoded

print_meta (optional)

Include metadata in output

bool

true

truncate_data (optional)

Truncate the data fields to the given number of bytes before printing. Set to 0 to disable

int32

100