Meta-Command Reference
This section describes meta-commands provided by gsql after the openGauss database CLI tool is used to connect to a database. A gsql meta-command can be anything that you enter in gsql and begins with an unquoted backslash.
Precautions
- The format of the gsql meta-command is a backslash (\) followed by a command verb, and then a parameter. The parameters are separated from the command verb and from each other by any number of whitespace characters.
- To include whitespace characters into an argument, you must quote them with a single straight quotation mark. To include a single straight quotation mark into such an argument, precede it by a backslash. Anything contained in single quotation marks is furthermore subject to C-like substitutions for \n (new line), \t (tab), \b (backspace), \r (carriage return), \f (form feed), \digits (octal), and \xdigits (hexadecimal).
- Within a parameter, text enclosed in double quotation marks ("") is taken as a command line input to the shell. The output of the command (with any trailing newline removed) is taken as the argument value.
- If an unquoted argument begins with a colon (:), the argument is taken as a gsql variable and the value of the variable is used as the argument value instead.
- Some commands take an SQL identifier (such as a table name) as a parameter. These parameters follow the SQL syntax rules: Unquoted letters are forced to lowercase, while double quotation marks ("") protect letters from case conversion and allow incorporation of whitespace into the identifier. Within double quotation marks, paired double quotation marks reduce to a single double quotation mark in the result name. For example, FOO"BAR"BAZ is interpreted as fooBARbaz, and “Aweird"“name” becomes A weird"name.
- Parsing for arguments stops when another unquoted backslash is found. This is taken as the beginning of a new meta-command. The special sequence \\ (two backslashes) marks the end of parameters and continues parsing SQL statements if any. In this way, SQL and gsql commands can be freely mixed in a line. But in any case, the arguments of a meta-command cannot continue beyond the end of the line.
Meta-command
For details about meta-commands, see Table 1, Table 2, Table 3, Table 4, Table 6, Table 8, Table 9, Table 10, and Table 12.
NOTICE: FILE mentioned in the following commands indicates a file path. This path can be an absolute path such as /home/gauss/file.txt or a relative path, such as file.txt. By default, a file.txt is created in the path where the user runs gsql commands.
Table 1 Common meta-commands
Table 2 Query buffer meta-commands
Edits the function definition using an external editor. If LINE is specified, the cursor will point to the specified line of the function body. | |
Table 3 Input/Output commands
NOTE: In Table 4, S indicates displaying the system object and + indicates displaying the additional description information of the object. PATTERN specifies the name of an object to be displayed.
Table 4 Information display meta-commands
Lists all tables, views, and sequences of all schemas in the search_path. When objects with the same name exist in different schemas in search_path, only the object in the schema that ranks first in search_path is displayed. | Lists all tables, views, and sequences of all schemas in the search_path. openGauss=# \d | ||
Lists the structure of specified tables, views, and indexes. | Lists the structure of table a. openGauss=# \dtable+ a | ||
If PATTERN is specified, only tables, views, and indexes whose names match PATTERN are displayed. | Lists all tables, views, and indexes whose names start with f. openGauss=# \d+ f* | ||
Lists all available aggregate functions, together with the data type they perform operations on and the return value types. | If PATTERN is specified, only aggregate functions whose names match PATTERN are displayed. | Lists all available aggregate functions whose names start with f, together with their return value types and the data types. openGauss=# \da f* | |
If PATTERN is specified, only tablespaces whose names match PATTERN are displayed. | Lists all available tablespaces whose names start with p. openGauss=# \db p* | ||
Lists all available conversions between character-set encodings. | If PATTERN is specified, only conversions whose names match PATTERN are displayed. | Lists all available conversions between character-set encodings. openGauss=# \dc * | |
Lists all available type conversions. PATTERN must be the actual type name and cannot be an alias. | If PATTERN is specified, only conversions whose names match PATTERN are displayed. | Lists all type conversions whose patten names start with c. openGauss=# \dC c* | |
If PATTERN is not specified, all visible objects are displayed. The objects include aggregations, functions, operators, types, relations (tables, views, indexes, sequences, and large objects), and rules. | openGauss=# \dd | ||
If PATTERN is specified, only permissions whose names match PATTERN are displayed. | Lists all default permissions. openGauss=# \ddp | ||
If PATTERN is specified, only domains whose names match PATTERN are displayed. | openGauss=# \dD | ||
If PATTERN is specified, only objects whose names match PATTERN are displayed. | Lists all Data Source objects. openGauss=# \ded | ||
If PATTERN is specified, only tables whose names match PATTERN are displayed. | openGauss=# \det | ||
If PATTERN is specified, only servers whose names match PATTERN are displayed. | openGauss=# \des | ||
If PATTERN is specified, only information whose name matches PATTERN is displayed. | openGauss=#\deu | ||
If PATTERN is specified, only data whose name matches PATTERN is displayed. | Lists all encapsulated external data. openGauss=# \dew | ||
Lists all available functions, together with their parameters and return types. a indicates an aggregate function, n indicates a common function, t indicates a trigger, and w indicates a window function. | If PATTERN is specified, only functions whose names match PATTERN are displayed. | Lists all available functions, together with their parameters and return types. openGauss=# \df | |
If PATTERN is specified, only configurations whose names match PATTERN are displayed. | Lists all text search configuration information. openGauss=# \dF+ | ||
If PATTERN is specified, only dictionaries whose names match PATTERN are displayed. | Lists all text search dictionaries. openGauss=# \dFd | ||
If PATTERN is specified, only analyzers whose names match PATTERN are displayed. | Lists all text search analyzers. openGauss=# \dFp | ||
If PATTERN is specified, only templates whose names match PATTERN are displayed. | Lists all text search templates. openGauss=# \dFt | ||
If PATTERN is specified, only roles whose names match PATTERN are displayed. | Lists all database roles whose names start with j and end with e. openGauss=# \dg j?e | ||
This is an alias for \lo_list, which shows a list of large objects. | openGauss=# \dl | ||
If PATTERN is specified, only languages whose names match PATTERN are displayed. | Lists all available program languages. openGauss=# \dL | ||
If PATTERN is specified, only materialized views whose names match PATTERN are displayed. | openGauss=# \dm | ||
Lists all schemas (namespace). If + is added to the command, the permission and description of each schema are listed. | If PATTERN is specified, only schemas whose names match the pattern are shown. By default, only schemas you created are displayed. | Lists information about all schemas whose names start with d. openGauss=# \dn+ d* | |
Lists available operators with their operand and return types. | If PATTERN is specified, only operators whose names match PATTERN are displayed. By default, only the operators created by the user are listed. | Lists available operators with their operand and return types. openGauss=# \do | |
If PATTERN is specified, only rules whose names match PATTERN are displayed. By default, only user-created rules are shown. | openGauss=# \dO | ||
Lists tables, views, and related permissions. The following result about \dp is displayed: rolename=xxxx/yyyy --Assigns permissions to a role. =xxxx/yyyy --Assigns permissions to public. xxxx indicates the assigned permissions, and yyyy indicates the roles with the assigned permissions. For details about permission descriptions, see Table 5. | If PATTERN is specified, only tables and views whose names match the pattern are shown. | Lists tables, views, and related permissions. openGauss=# \dp | |
Lists all parameters that have been modified. These settings can be for roles, for databases, or for both. PATTERN1 and PATTERN2 indicate a role pattern and a database pattern, respectively. | If PATTERN is specified, only collations rules whose names match PATTERN are displayed. If the default value is used or * is specified, all settings are listed. | Lists all modified configuration parameters of the postgres database. openGauss=# \drds *openGausss | |
If PATTERN is specified, only types whose names match PATTERN are displayed. | openGauss=# \dT | ||
If PATTERN is specified, only roles whose names match PATTERN are displayed. | openGauss=# \du | ||
In this group of commands, the letters E, i, s, t, and v stand for foreign table, index, sequence, table, and view, respectively. You can specify any or a combination of these letters sequenced in any order to obtain an object list. For example, \dit lists all indexes and tables. If + is added to the end of a command name, the physical size and related description of each object are also listed. | If PATTERN is specified, only objects whose names match PATTERN are displayed. By default, only objects you created are displayed. You can specify PATTERN or S to view other system objects. | openGauss=# \div | |
If PATTERN is specified, only extensions whose names match PATTERN are displayed. | openGauss=# \dx | ||
Lists the names, owners, character set encodings, and permissions of all the databases in the server. | List the names, owners, character set encodings, and permissions of all the databases in the server. openGauss=# \l | ||
Assume a function function_a and a function func()name. This parameter will be as follows: openGauss=# \sf function_a openGauss=# \sf "func()name"(argtype1, argtype2) | |||
Lists all tables, views, and sequences in the database and their access permissions. | If a pattern is given, it is a regular expression, and only matched tables, views, and sequences are shown. | Lists all tables, views, and sequences in the database and their access permissions. openGauss=# \z |
Table 5 Description of permissions
Table 6 Formatting meta-commands
Switches between aligned and unaligned table output formats. | |
Sets the title of any table being printed as the result of a query or unsets any such title. | |
| |
Sets options affecting the output of query result tables. For details about the value of NAME, see Table 7. | |
Switches the display of output name information and row count footer. | |
Specifies attributes to be placed within the table tag in HTML output format. If this parameter is empty, no attribute is specified. | |
Table 7 Adjustable printing options
Table 8 Connection meta-commands
Table 9 OS meta-commands
Table 10 Variable meta-commands
Sets the NAME internal variable to VALUE. If more than one value is provided, NAME is set to the concatenation of all of them. If no second argument is given, the variable is just set with no value. Some common variables are processed differently in gsql and they are combinations of uppercase letters, numbers and underscores. Table 11 describes a list of variables that are processed in a way different from other variables. | |
Table 11 Common \set commands
Table 12 Large object meta-commands
Displays a list of all openGauss large objects stored in the database, along with the comments provided for them. |
PATTERN
The various \d commands accept a PATTERN parameter to specify the object name to be displayed. In the simplest case, PATTERN is the exact name of the object. Characters in PATTERN are usually converted to lowercase (as in SQL names), for example, \dt FOO will display a table named foo. As in SQL names, placing double quotation marks (”) around a pattern prevents them being folded to lower case. If you need to include a double quotation mark (") in a pattern, write it as a pair of double quotation marks ("") within a double-quote sequence, which is in accordance with the rules for SQL quoted identifiers. For example, \dt “FOO"“BAR” will be displayed as a table named FOO"BAR instead of foo"bar. You cannot put double quotation marks around just part of a pattern, which is different from the normal rules for SQL names. For example, \dt FOO"FOO"BAR will be displayed as a table named fooFOObar if just part of a pattern is quoted.
Whenever the PATTERN parameter is omitted completely, the **\d **commands display all objects that are visible in the current schema search path, which is equivalent to using an asterisk (*) as the pattern. An object is regarded to be visible if it can be referenced by name without explicit schema qualification. To see all objects in the database regardless of their visibility, use a dot within double quotation marks (*.*) as the pattern.
Within a pattern, the asterisk (*) matches any sequence of characters (including no characters) and a question mark (?) matches any single character. This notation is comparable to Unix shell file name patterns. For example, \dt int* displays tables whose names start with int. But within double quotation marks, the asterisk (*) and the question mark (?) lose these special meanings and are just matched literally.
A pattern that contains a dot (.) is interpreted as a schema name pattern followed by an object name pattern. For example, \dt foo*.*bar* displays all tables (whose names include bar) in schemas starting with foo. If no dot appears, then the pattern matches only visible objects in the current schema search path. Likewise, the dot within double quotation marks loses its special meaning and becomes an ordinary character.
Senior users can use regular-expression notations, such as character classes. For example [0-9] can be used to match any digit. All regular-expression special characters work as specified in POSIX. The following characters are excluded:
- A dot (.) is used as a separator.
- An asterisk (*) is translated into an asterisk prefixed with a dot (.*), which is a regular-expression marking.
- A question mark (?) is translated into a dot (.).
- A dollar sign ($) is matched literally.
You can write ?, (R+|), (R|), and R to the following pattern characters: ., R*, and R?. The dollar sign ($) does not need to be used as a regular expression character because PATTERN must match the entire name instead of being interpreted as a regular expression (in other words, $ is automatically appended to PATTERN). If you do not expect a pattern to be anchored, write an asterisk (*) at its beginning or end. All regular-expression special characters within double quotation marks lose their special meanings and are matched literally. Regular-expression special characters in operator name patterns (such as the \do parameter) are also matched literally.