impala-shell Command Reference

Use the following commands within impala-shell to pass requests to the impalad daemon that the shell is connected to. You can enter a command interactively at the prompt, or pass it as the argument to the -q option of impala-shell. Most of these commands are passed to the Impala daemon as SQL statements; refer to the corresponding SQL language reference sections for full syntax details.

Command Explanation

alter

Changes the underlying structure or settings of an Impala table, or a table shared between Impala and Hive. See ALTER TABLE Statement and ALTER VIEW Statement for details.

compute stats

Gathers important performance-related information for a table, used by Impala to optimize queries. See COMPUTE STATS Statement for details.

connect

Connects to the specified instance of impalad. The default port of 21000 is assumed unless you provide another value. You can connect to any host in your cluster that is running impalad. If you connect to an instance of impalad that was started with an alternate port specified by the --fe_port flag, you must provide that alternate port. See Connecting to impalad through impala-shell for examples.

The SET statement has no effect until the impala-shell interpreter is connected to an Impala server. Once you are connected, any query options you set remain in effect as you issue a subsequent CONNECT command to connect to a different Impala host.

describe

Shows the columns, column data types, and any column comments for a specified table. DESCRIBE FORMATTED shows additional information such as the HDFS data directory, partitions, and internal properties for the table. See DESCRIBE Statement for details about the basic DESCRIBE output and the DESCRIBE FORMATTED variant. You can use DESC as shorthand for the DESCRIBE command.

drop

Removes a schema object, and in some cases its associated data files. See DROP TABLE Statement, DROP VIEW Statement, DROP DATABASE Statement, and DROP FUNCTION Statement for details.

explain

Provides the execution plan for a query. EXPLAIN represents a query as a series of steps. For example, these steps might be map/reduce stages, metastore operations, or file system operations such as move or rename. See EXPLAIN Statement and Using the EXPLAIN Plan for Performance Tuning for details.

help

Help provides a list of all available commands and options.

history

Maintains an enumerated cross-session command history. This history is stored in the ~/.impalahistory file.

insert

Writes the results of a query to a specified table. This either overwrites table data or appends data to the existing table content. See INSERT Statement for details.

invalidate metadata

Updates impalad metadata for table existence and structure. Use this command after creating, dropping, or altering databases, tables, or partitions in Hive. See INVALIDATE METADATA Statement for details.

profile

Displays low-level information about the most recent query. Used for performance diagnosis and tuning. The report starts with the same information as produced by the EXPLAIN statement and the SUMMARY command. See Using the Query Profile for Performance Tuning for details.

quit

Exits the shell. Remember to include the final semicolon so that the shell recognizes the end of the command.

refresh

Refreshes impalad metadata for the locations of HDFS blocks corresponding to Impala data files. Use this command after loading new data files into an Impala table through Hive or through HDFS commands. See REFRESH Statement for details.

rerun or @

Executes a previous impala-shell command again, from the list of commands displayed by the history command. These could be SQL statements, or commands specific to impala-shell such as quit or profile.

Specify an integer argument. A positive integer N represents the command labelled N in the output of the HISTORY command. A negative integer -N represents the Nth command from the end of the list, such as -1 for the most recent command. Commands that are executed again do not produce new entries in the HISTORY output list.

select

Specifies the data set on which to complete some action. All information returned from select can be sent to some output such as the console or a file or can be used to complete some other element of query. See SELECT Statement for details.

set

Manages query options for an impala-shell session. The available options are the ones listed in Query Options for the SET Statement. These options are used for query tuning and troubleshooting. Issue SET with no arguments to see the current query options, either based on the impalad defaults, as specified by you at impalad startup, or based on earlier SET statements in the same session. To modify option values, issue commands with the syntax set option=value. To restore an option to its default, use the unset command. Some options take Boolean values of true and false. Others take numeric arguments, or quoted string values.

The SET statement has no effect until the impala-shell interpreter is connected to an Impala server. Once you are connected, any query options you set remain in effect as you issue a subsequent CONNECT command to connect to a different Impala host.

In Impala 2.0 and later, SET is available as a SQL statement for any kind of application, not only through impala-shell. See SET Statement for details.

In Impala 2.5 and later, you can use SET to define your own substitution variables within an impala-shell session. Within a SQL statement, you substitute the value by using the notation ${var:variable_name}.

shell

Executes the specified command in the operating system shell without exiting impala-shell. You can use the ! character as shorthand for the shell command.

show

Displays metastore data for schema objects created and accessed through Impala, Hive, or both. show can be used to gather information about objects such as databases, tables, and functions. See SHOW Statement for details.

source or src

Executes one or more statements residing in a specified file from the local filesystem. Allows you to perform the same kinds of batch operations as with the -f option, but interactively within the interpreter. The file can contain SQL statements and other impala-shell commands, including additional SOURCE commands to perform a flexible sequence of actions. Each command or statement, except the last one in the file, must end with a semicolon. See Running Commands and SQL Statements in impala-shell for examples.

summary

Summarizes the work performed in various stages of a query. It provides a higher-level view of the information displayed by the EXPLAIN command. Added in Impala 1.4.0. See Using the SUMMARY Report for Performance Tuning for details about the report format and how to interpret it.

The time, memory usage, and so on reported by SUMMARY only include the portions of the statement that read data, not when data is written. Therefore, the PROFILE command is better for checking the performance and scalability of INSERT statements.

In CDH 5.5 / Impala 2.3 and higher, you can see a continuously updated report of the summary information while a query is in progress. See LIVE_SUMMARY Query Option (CDH 5.5 or higher only) for details.

unset

Removes any user-specified value for a query option and returns the option to its default value. See Query Options for the SET Statement for the available query options.

In CDH 5.7 / Impala 2.5 and higher, it can also remove user-specified substitution variables using the notation UNSET VAR:variable_name.

use

Indicates the database against which to execute subsequent commands. Lets you avoid using fully qualified names when referring to tables in databases other than default. See USE Statement for details. Not effective with the -q option, because that option only allows a single statement in the argument.

version

Returns Impala version information.