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 (see below for many examples) and is different from the standalone CALL statement used for changing 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 Kùzu
`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

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 Kùzu, 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 Kùzu, 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 Kùzu Inc., or 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'); │
└────────────┴────────────┴────────────┴─────────────────────────┴──────────────────┴──────────────────────────────────────────────────────────────────────────────────────────────────┘

Using 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

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_num
RETURN *;

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_pk
CALL 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_pk
RETURN *;

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       │
└───────────┴─────────────┴─────────────┴────────────────┴───────────┴────────────┴──────────────┴──────────────┴─────────────────┴────────────┘

If the YIELD clause is used after a CALL function, all return columns of the function must appear in the YIELD clause.

For example:

CALL table_info('person')
YIELD `property id` as person_id
RETURN person_id

The query throws an exception since not all returns columns of the table_info function appear in the yield clause.

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_num
RETURN *;

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.

The syntax in Kùzu Cypher is different from other systems like Neo4j. In Kùzu, the YIELD clause must be followed by a return clause. YIELD * is not allowed in Kùzu.