Call
The CALL
clause is used for executing schema functions. This way of using CALL
needs to be followed
with other query clauses, such as RETURN
or YIELD
(see below for example usage). Note that the CALL
clause
defined here is different from the standalone CALL
statement used for changing
the database configuration.
The following tables lists the built-in schema functions you can use with the CALL
clause:
Function | Description |
---|---|
CURRENT_SETTING('setting') | returns the value of the given setting |
DB_VERSION() | returns the version of Kuzu |
SHOW_TABLES() | returns the name, type, comment of all tables in the database |
SHOW_CONNECTION('tableName') | returns the source/destination nodes for a relationship/relgroup in the database |
SHOW_ATTACHED_DATABASES() | returns the name, type of all attached databases |
SHOW_FUNCTIONS() | returns all registered functions in the database |
SHOW_WARNINGS() | returns the contents of the Warnings Table |
CLEAR_WARNINGS() | clears all warnings in the Warnings Table |
TABLE_INFO('tableName') | returns metadata information of the given table |
SHOW_OFFICIAL_EXTENSIONS | returns all official extensions which can be installed by INSTALL <extension_name> |
SHOW_LOADED_EXTENSIONS | returns all loaded extensions |
SHOW_INDEXES | returns all indexes built in the system |
SHOW_PROJECTED_GRAPHS | returns all existing projected graphs in the system |
Functions
This section describes the schema functions that you can use with the CALL
clause.
TABLE_INFO
TABLE_INFO
takes table name as a parameter and returns metadata information of the table.
Column | Description | Type |
---|---|---|
property id | Internal identifier of the property within table | INT64 |
name | name of the property | STRING |
type | data type of the property | STRING |
default expression | default value of property when none is specified | STRING |
primary key | if property is primary key | BOOLEAN |
CALL TABLE_INFO('User') RETURN *;
Output:
βββββββββββββββ¬βββββββββββββββ¬βββββββββ¬βββββββββββββββββββββββ¬ββββββββββββββββ property id β name β type β default expression β primary key ββ INT32 β STRING β STRING β STRING β BOOL ββββββββββββββββΌβββββββββββββββΌβββββββββΌβββββββββββββββββββββββΌβββββββββββββββ€β 0 β name β STRING β NULL β True ββ 1 β age β INT64 β 0 β False ββββββββββββββββ΄βββββββββββββββ΄βββββββββ΄βββββββββββββββββββββββ΄βββββββββββββββ
CURRENT_SETTING
CURRENT_SETTING
returns the value of given database configuration.
CALL current_setting('threads') RETURN *;
Output:
ββββββββββββ threads ββ STRING ββββββββββββ€β 12 ββββββββββββ
DB_VERSION
DB_VERSION
returns current database version.
Column | Description | Type |
---|---|---|
version | database version | STRING |
CALL db_version() RETURN *;
Output:
ββββββββββββ version ββ STRING ββββββββββββ€β 0.x.0 ββββββββββββ
SHOW_TABLES
SHOW_TABLES
returns the id, name, type and comment of all tables in the database.
Column | Description | Type |
---|---|---|
id | id of the table | INT |
name | name of the table | STRING |
type | type of the table | STRING |
comment | comment of the table | STRING |
CALL show_tables() RETURN *;
Output:
ββββββββββ¬ββββββββββ¬βββββββββ¬ββββββββββββββββ¬βββββββββββ id β name β type β database name β comment ββ UINT64 β STRING β STRING β STRING β STRING βββββββββββΌββββββββββΌβββββββββΌββββββββββββββββΌββββββββββ€β 0 β User β NODE β local(kuzu) β ββ 2 β Follows β REL β local(kuzu) β ββ 1 β City β NODE β local(kuzu) β ββ 3 β LivesIn β REL β local(kuzu) β βββββββββββ΄ββββββββββ΄βββββββββ΄ββββββββββββββββ΄ββββββββββ
SHOW_CONNECTION
SHOW_CONNECTION
returns the source/destination nodes for a relationship/relationship group in the database.
Column | Description | Type |
---|---|---|
source table name | name of the source node table | STRING |
destination table name | name of the destination node table | STRING |
source table primary key | primary key of the source node table | STRING |
destination table primary key | primary key of the destination node table | STRING |
Show connection on a relationship table:
CALL show_connection('LivesIn') RETURN *;
Output:
βββββββββββββββββββββ¬βββββββββββββββββββββββββ¬βββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββ source table name β destination table name β source table primary key β destination table primary key ββ STRING β STRING β STRING β STRING ββββββββββββββββββββββΌβββββββββββββββββββββββββΌβββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββββ€β User β City β name β name ββββββββββββββββββββββ΄βββββββββββββββββββββββββ΄βββββββββββββββββββββββββββ΄ββββββββββββββββββββββββββββββββ
SHOW_ATTACHED_DATABASES
SHOW_ATTACHED_DATABASES
returns the name, database type of all attached databases.
name | db_type |
---|---|
name | name of the attached databases |
db_type | type of the table |
CALL show_attached_databases() RETURN *;
Output:
βββββββββββββββ¬ββββββββββββββββββ name β database type ββ STRING β STRING ββββββββββββββββΌβββββββββββββββββ€β tinysnb β DUCKDB ββ anotherdb β POSTGRES ββββββββββββββββ΄βββββββββββββββββ
SHOW_WARNINGS
SHOW_WARNINGS
returns the contents of the
Warnings Table. This is a feature
related to ignoring errors when running COPY/LOAD FROM
statements to scan files.
They will only be reported if the IGNORE_ERRORS
setting is enabled.
Note that the number of warnings that are stored is limited by the warning_limit
parameter.
See configuration for more details on how to set the warning limit.
After warning_limit
many warnings are stored, any new warnings generated will not be stored.
Column | Description | Type |
---|---|---|
query_id | The query that triggered the warning | UINT64 |
message | A description of what triggered the warning | STRING |
file_path | The path to the file that triggered the warning | STRING |
line_number | The line number in the file that triggered the warning. | UINT64 |
skipped_line_or_record | The line or record (depending on the type of file that is being read from) containing the actual value that triggered the warning. For example, for CSV files this will be the line number and for JSON files this will be the record number. | STRING |
CALL show_warnings() RETURN *;
Output:
ββββββββββββ¬ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ¬ββββββββββββββ¬ββββββββββββββ¬ββββββββββββββββββββββββββ query_id β message β file_path β line_number β skipped_line_or_record ββ UINT64 β STRING β STRING β UINT64 β STRING βββββββββββββΌββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββΌββββββββββββββΌββββββββββββββΌβββββββββββββββββββββββββ€β 1 β Conversion exception: Cast failed. Could not convert "2147483650" to INT32. β vPerson.csv β 2 β 2,2147483650 βββββββββββββ΄ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ΄ββββββββββββββ΄ββββββββββββββ΄βββββββββββββββββββββββββ
CLEAR_WARNINGS
If you would like to clear the contents of the Warnings Table, you can run the CLEAR_WARNINGS
function.
This function has no output.
CALL clear_warnings();
SHOW_OFFICIAL_EXTENSIONS
If you would like to know all official extensions available in Kuzu, you can run the SHOW_OFFICIAL_EXTENSIONS
function.
Column | Description | Type |
---|---|---|
name | name of the extension | STRING |
description | description of the extension | STRING |
CALL SHOW_OFFICIAL_EXTENSIONS() RETURN *;
Output:
ββββββββββββ¬βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ name β description ββ STRING β STRING βββββββββββββΌββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€β SQLITE β Adds support for reading from SQLITE tables ββ JSON β Adds support for JSON operations ββ ICEBERG β Adds support for reading from iceberg tables ββ HTTPFS β Adds support for reading and writing files over a HTTP(S)/S3 filesystem ββ DELTA β Adds support for reading from delta tables ββ POSTGRES β Adds support for reading from POSTGRES tables ββ FTS β Adds support for full-text search indexes ββ DUCKDB β Adds support for reading from duckdb tables βββββββββββββ΄ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
SHOW_LOADED_EXTENSIONS
If you would like to know information about loaded extensions in Kuzu, you can run the SHOW_LOADED_EXTENSIONS
function.
Column | Description | Type |
---|---|---|
extension name | name of the extension | STRING |
extension source | whether the extension is officially supported by the Kuzu team or is developed by a third-party | STRING |
extension path | the path to the extension | STRING |
CALL SHOW_LOADED_EXTENSIONS() RETURN *;
ββββββββββββββββββ¬βββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ extension name β extension source β extension path ββ STRING β STRING β STRING βββββββββββββββββββΌβββββββββββββββββββΌββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€β FTS β OFFICIAL β extension/fts/build/libfts.kuzu_extension βββββββββββββββββββ΄βββββββββββββββββββ΄ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
SHOW_INDEXES
If you would like to know information about indexes built in kuzu, you can run the SHOW_INDEXES
function.
Column | Description | Type |
---|---|---|
table name | the table which the index is built on | STRING |
index name | the name of the index | STRING |
index type | the type of the index (e.g. FTS, HNSW) | STRING |
property names | the properties which the index is built on | STRING[] |
extension loaded | whether the depended extension has been loaded | BOOL |
index definition | the cypher query to create the index | STRING |
Note: Some indexes are implemented within extensions. If a required extension is not loaded, the extension loaded field will display false, and the index definition field will be null.
CALL SHOW_INDEXES() RETURN *;
ββββββββββββββ¬βββββββββββββ¬βββββββββββββ¬ββββββββββββββββββββββββββ¬βββββββββββββββββββ¬ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ table name β index name β index type β property names β extension loaded β index definition ββ STRING β STRING β STRING β STRING[] β BOOL β STRING βββββββββββββββΌβββββββββββββΌβββββββββββββΌββββββββββββββββββββββββββΌβββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€β book β bookIdx β FTS β [abstract,author,title] β True β CALL CREATE_FTS_INDEX('book', 'bookIdx', ['abstract', 'author', 'title' ], stemmer := 'porter'); βββββββββββββββ΄βββββββββββββ΄βββββββββββββ΄ββββββββββββββββββββββββββ΄βββββββββββββββββββ΄βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
SHOW_PROJECTED_GRAPH
To list all existing projected graphs in a Kuzu database, you can use the SHOW_PROJECTED_GRAPH
function.
Column | Description | Type |
---|---|---|
name | the name of the projected graph | STRING |
nodes | the nodes with predicates in the projected graph | STRING |
rels | the rels with predicates in the projected graph | STRING |
CALL SHOW_PROJECTED_GRAPH() RETURN *;
ββββββββββββββββββ¬ββββββββββββββββββββββββ¬ββββββββββββββββββββββββ name β nodes β rels ββ STRING β STRING β STRING βββββββββββββββββββΌββββββββββββββββββββββββΌβββββββββββββββββββββββ€β social_network β [{'table': 'person'}] β [{'table': 'knows'}] βββββββββββββββββββ΄ββββββββββββββββββββββββ΄βββββββββββββββββββββββ
YIELD
The YIELD
clause in Kuzu is used to rename the return columns of a CALL
function to avoid naming conflicition and better readability.
Usage:
CALL FUNC()YIELD COLUMN0 [AS ALIAS0], COLUMN1 [AS ALIAS1]RETURN ALIAS0, ALIAS1
Below is an example. To rename the output column name of current_setting('threads')
from threads
to threads_num
, you can use the following query:
CALL current_setting('threads')YIELD threads as threads_numRETURN *;
Result:
ββββββββββββββββ threads_num ββ STRING ββββββββββββββββ€β 10 ββββββββββββββββ
Another useful scenario is to avoid naming conflicition when two call functions in the same query returns a column with the same name.
CALL table_info('person')YIELD `property id` as person_id, name as person_name, type as person_type, `default expression` as person_default, `primary key` as person_pkCALL table_info('student')YIELD `property id` as student_id, name as student_name, type as student_type, `default expression` as student_default, `primary key` as student_pkRETURN *;
Result:
βββββββββββββ¬ββββββββββββββ¬ββββββββββββββ¬βββββββββββββββββ¬ββββββββββββ¬βββββββββββββ¬βββββββββββββββ¬βββββββββββββββ¬ββββββββββββββββββ¬ββββββββββββββ person_id β person_name β person_type β person_default β person_pk β student_id β student_name β student_type β student_default β student_pk ββ INT32 β STRING β STRING β STRING β BOOL β INT32 β STRING β STRING β STRING β BOOL ββββββββββββββΌββββββββββββββΌββββββββββββββΌβββββββββββββββββΌββββββββββββΌβββββββββββββΌβββββββββββββββΌβββββββββββββββΌββββββββββββββββββΌβββββββββββββ€β 0 β id β INT64 β NULL β True β 0 β id β INT64 β NULL β True ββββββββββββββ΄ββββββββββββββ΄ββββββββββββββ΄βββββββββββββββββ΄ββββββββββββ΄βββββββββββββ΄βββββββββββββββ΄βββββββββββββββ΄ββββββββββββββββββ΄βββββββββββββ
All columns must appear in the YIELD
clause
If the YIELD
clause is used after a CALL
function, all return columns of the function must appear in the YIELD
clause. Using YIELD *
is not allowed in Kuzu.
For example:
CALL table_info('person')YIELD `property id` as person_idRETURN person_id
The query throws an exception since not all returns columns of the table_info
function appear in the yield clause.
Column names must match origin
The column names to yield must match the original return column names of the call function. For example:
CALL current_setting('threads')YIELD thread as threads_numRETURN *;
The query throws an exception since the column name to yield is thread
which doesnβt match the return column name(threads
) of the call function.