/show/table

URL: http://<db.host>:<db.port>/show/table

Retrieves detailed information about a table, view, or schema, specified in input parameter table_name. If the supplied input parameter table_name is a schema the call can return information about either the schema itself or the tables and views it contains. If input parameter table_name is empty, information about all schemas will be returned.

If the option get_sizes is set to true, then the number of records in each table is returned (in output parameter sizes and output parameter full_sizes), along with the total number of objects across all requested tables (in output parameter total_size and output parameter total_full_size).

For a schema, setting the show_children option to false returns only information about the schema itself; setting show_children to true returns a list of tables and views contained in the schema, along with their corresponding detail.

To retrieve a list of every table, view, and schema in the database, set input parameter table_name to '*' and show_children to true. When doing this, the returned output parameter total_size and output parameter total_full_size will not include the sizes of non-base tables (e.g., filters, views, joins, etc.).

Input Parameter Description

Name

Type

Description

table_name

string

Name of the table for which to retrieve the information, in [schema_name.]table_name format, using standard name resolution rules. If blank, then returns information about all tables and views.

options

map of string to strings

Optional parameters. The default value is an empty map ( {} ).

Supported Parameters (keys)	Parameter Description
dependencies	Include view dependencies in the output The default value is false. The supported values are: true false
force_synchronous	If true then the table sizes will wait for read lock before returning. The default value is true. The supported values are: true false
get_access_data	If true then data about the last read, write, alter and create will be returned. The default value is false. The supported values are: true false
get_cached_sizes	If true then the number of records in each table, along with a cumulative count, will be returned; blank, otherwise. This version will return the sizes cached at rank 0, which may be stale if there is a multihead insert occurring. The default value is false. The supported values are: true false
get_sizes	If true then the number of records in each table, along with a cumulative count, will be returned; blank, otherwise. The default value is false. The supported values are: true false
skip_additional_info	If true then the response will not populate the additional_info field. The default value is false. The supported values are: true false
no_error_if_not_exists	If false will return an error if the provided input parameter table_name does not exist. If true then it will return an empty result. The default value is false. The supported values are: true false
skip_temp_schemas	If true then the table list will not include tables from SYS_TEMP and other system temporary schemas. This is the default behavior for non-admin users. The default value is false. The supported values are: true false
show_children	If input parameter table_name is a schema, then true will return information about the tables and views in the schema, and false will return information about the schema itself. If input parameter table_name is a table or view, show_children must be false. If input parameter table_name is empty, then show_children must be true. The default value is true. The supported values are: true false
get_column_info	If true then column info (memory usage, etc) will be returned. The default value is false. The supported values are: true false

Output Parameter Description

The GPUdb server embeds the endpoint response inside a standard response structure which contains status information and the actual response to the query. Here is a description of the various fields of the wrapper:

Name

Type

Description

status

String

'OK' or 'ERROR'

message

String

Empty if success or an error message

data_type

String

'show_table_response' or 'none' in case of an error

data

String

Empty string

data_str

JSON or String

This embedded JSON represents the result of the /show/table endpoint:

Name

Type

Description

table_name

string

Value of input parameter table_name.

table_names

array of strings

If input parameter table_name is a table or view, then the single element of the array is input parameter table_name. If input parameter table_name is a schema and show_children is set to true, then this array is populated with the names of all tables and views in the given schema; if show_children is false, then this array will only include the schema name itself. If input parameter table_name is an empty string, then the array contains the names of all tables in the user's default schema.

table_descriptions

array of arrays of strings

List of descriptions for the respective tables in output parameter table_names. Possible values are:

COLLECTION
JOIN
LOGICAL_EXTERNAL_TABLE
LOGICAL_VIEW
MATERIALIZED_EXTERNAL_TABLE
MATERIALIZED_VIEW
MATERIALIZED_VIEW_MEMBER
MATERIALIZED_VIEW_UNDER_CONSTRUCTION
REPLICATED
RESULT_TABLE
SCHEMA
VIEW

type_ids

array of strings

Type IDs of the respective tables in output parameter table_names.

type_schemas

array of strings

Type schemas of the respective tables in output parameter table_names.

type_labels

array of strings

Type labels of the respective tables in output parameter table_names.

properties

array of maps of string to arrays of strings

Property maps of the respective tables in output parameter table_names.

additional_info

array of maps of string to strings

Additional information about the respective tables in output parameter table_names.

Possible List Entries

Description

map of string to strings

The default value is an empty map ( {} ).

Possible Parameters (keys)

Parameter Description

request_avro_type

Method by which this table was created. Possible values are:

create_table
create_projection
create_union

request_avro_json

The JSON representation of request creating this table. The default value is ''.

protected

No longer used. Indicated whether the respective table was protected or not. Possible values are:

true
false

record_bytes

The number of in-memory bytes per record which is the sum of the byte sizes of all columns with property 'data'.

total_bytes

The total size in bytes of all data stored in the table.

collection_names

[DEPRECATED--use schema_name instead] This will now contain the name of the schema for the table. There can only be one schema for a table.

schema_name

The name of the schema for the table. There can only be one schema for a table.

table_ttl

The value of the time-to-live setting. Not present for schemas.

remaining_table_ttl

The remaining time-to-live, in minutes, before the respective table expires (-1 if it will never expire). Not present for schemas.

primary_key_type

The primary key type of the table (if it has a primary key).

Possible Values	Description
memory	In-memory primary key
disk	On-disk primary key

foreign_keys

Semicolon-separated list of foreign keys, of the format 'source_column references target_table(primary_key_column)'. Not present for schemas. The default value is ''.

foreign_shard_key

Foreign shard key description of the format: <fk_foreign_key> references <pk_column_name> from <pk_table_name>(<pk_primary_key>). Not present for schemas. The default value is ''.

partition_type

Partitioning scheme used for this table The default value is NONE.

Possible Values	Description
RANGE	Using range partitioning
INTERVAL	Using interval partitioning
LIST	Using manual list partitioning
HASH	Using hash partitioning.
SERIES	Using series partitioning.
NONE	Using no partitioning

partition_keys

Comma-separated list of partition keys. The default value is ''.

partition_definitions

Comma-separated list of partition definitions, whose format depends on the partition_type. See partitioning documentation for details. The default value is ''.

is_automatic_partition

True if partitions will be created for LIST VALUES which don't fall into existing partitions. The default value is ''.

attribute_indexes

Semicolon-separated list of indexes. For column (attribute) indexes, only the indexed column name will be listed. For other index types, the index type will be listed with the colon-delimited indexed column(s) and the comma-delimited index option(s) using the form: <index_type>@<column_list>@<column_options>. Not present for schemas. The default value is ''.

column_info

JSON-encoded string representing a map of column name to information including memory usage if the get_column_info option is true. The default value is ''.

global_access_mode

Returns the global access mode (i.e. lock status) for the table.

Possible Values	Description
no_access	No read/write operations are allowed on this table.
read_only	Only read operations are allowed on this table.
write_only	Only write operations are allowed on this table.
read_write	All read/write operations are allowed on this table.

view_table_name

For materialized view the name of the view this member table is part of - if same as the table_name then this is the root of the view. The default value is ''.

is_view_persisted

True if the view named view_table_name is persisted - reported for each view member. Means method of recreating this member is saved - not the members data. The default value is ''.

is_dirty

True if some input table of the materialized view that affects this member table has been modified since the last refresh. The default value is ''.

refresh_method

For materialized view current refresh_method - one of manual, periodic, on_change. The default value is ''.

refresh_start_time

For materialized view with periodic refresh_method the initial datetime string that periodic refreshes began. The default value is ''.

refresh_stop_time

Time at which the periodic view refresh stops. The default value is ''.

refresh_period

For materialized view with periodic refresh_method the current refresh period in seconds. The default value is ''.

last_refresh_time

For materialized view the datetime string indicating the last time the view was refreshed. The default value is ''.

next_refresh_time

For materialized view with periodic refresh_method a datetime string indicating the next time the view is to be refreshed. The default value is ''.

user_chunk_size

User-specified number of records per chunk, if provided at table creation time. The default value is ''.

user_chunk_column_max_memory

User-specified target max bytes per column in a chunk, if provided at table creation time. The default value is ''.

user_chunk_max_memory

User-specified target max bytes for all columns in a chunk, if provided at table creation time. The default value is ''.

owner_resource_group

Name of the owner resource group. The default value is ''.

alternate_shard_keys

Semicolon-separated list of shard keys that were equated in joins (applicable for join tables). The default value is ''.

datasource_subscriptions

Semicolon-separated list of datasource names the table has subscribed to. The default value is ''.

null_modifying_columns

Comma-separated list of null modifying column names. The default value is ''.

compression_codec

Default compression codec for the table. The default value is ''.

created_by

User that created this table or view. The default value is ''.

created_time

Time (UTC) when this table or view was created. The default value is ''.

last_read_by

User that last read this table or view. The default value is ''.

last_read_time

Time (UTC) when this table or view was last read. The default value is ''.

read_count

Count of times this table or view was read. The default value is ''.

last_write_by

User that last wrote to this table. The default value is ''.

last_write_time

Time (UTC) when this table was last written. The default value is ''.

write_count

Count of times this table was written. The default value is ''.

last_alter_by

User that last altered this table or view. The default value is ''.

last_alter_time

Time (UTC) when this table or view was last altered. The default value is ''.

alter_count

Count of times this table or view was altered. The default value is ''.

sizes

array of longs

If get_sizes is true, an array containing the number of records of each corresponding table in output parameter table_names. Otherwise, an empty array.

full_sizes

array of longs

If get_sizes is true, an array containing the number of records of each corresponding table in output parameter table_names (same values as output parameter sizes). Otherwise, an empty array.

join_sizes

array of doubles

If get_sizes is true, an array containing the number of unfiltered records in the cross product of the sub-tables of each corresponding join-table in output parameter table_names. For simple tables, this number will be the same as output parameter sizes. For join-tables, this value gives the number of joined-table rows that must be processed by any aggregate functions operating on the table. Otherwise, (if get_sizes is false), an empty array.

total_size

long

If get_sizes is true, the sum of the elements of output parameter sizes. Otherwise, -1.

total_full_size

long

If get_sizes is true, the sum of the elements of output parameter full_sizes (same value as output parameter total_size). Otherwise, -1.

info

map of string to strings

Additional information.

Empty string in case of an error.