Kuneiform Introduction

Kuneiform is a language for defining databases on Kwil. It is capable of defining the structure of the database, queries for modifying and accessing data, and business logic for enforcing rules around data. Code in Kuneiform is written in blocks. All blocks are given a name, which must be unique from all other blocks in the same schema.

tip

You can write, parse, and deploy Kuneiform, as well as view sample Kuneiform files, online at https://admin.kwil.com/ide.

If you are using Visual Studio Code, you can install the Kuneiform extension from the VSCode Marketplace.

social_network.kf

database social_network;

// table for storing users
// each wallet can have a user
table users {
    id int primary notnull,
    username text notnull unique minlen(5) maxlen(32),
    age int notnull max(150),
    address text notnull unique // wallet address
}

// a public procedure for creating a user
// it will store the user's wallet address
procedure create_user ($id int, $username text, $age int) public {
    INSERT INTO users
    VALUES ($id, $username, $age, @caller); // @caller is the wallet address of the calling user
}

// a public, read-only procedure for getting all users
procedure get_users() public view returns table(username text, age int) {
    return SELECT username, age FROM users;
}

Data Types

Below is a list of all supported data types in Kuneiform.

Data Type	Description
int	A 64-bit integer.
text	A string of text.
bool	A boolean value.
blob	A binary large object.
uuid	A 128-bit universally unique identifier.
decimal(precision, scale)	A fixed-point number, that can be defined with a precision and scale between 1 and 1000.
uint256	A 256-bit unsigned integer.

Kuneiform also supports 1-dimensional arrays for all data types. To declare an array, simple include square brackets:

   table users {
       id int primary,
       names text[] notnull
   }

Contextual Variables

Kuneiform supports "contextual variables", which allow you to access information about the current transaction. Contextual variables can be accessed anywhere regular variables can be accessed, and are prefixed with an @ symbol. The following contextual variables are available:

Variable	Data Type	Description
@caller	text	The wallet address of the user calling the procedure.
@signer	blob	The signing address / public key of the user calling the procedure.
@txid	text	The transaction ID of the current transaction. If called in a read-only connection, it is empty.
@height	int	The height of the current block. If called in a read-only connection, it is -1.
@foreign_caller	text	The DBID of the calling database, if a procedure was called via a foreign procedure. It is an empty string if the procedure was called directly.
@block_timestamp	int	The Unix timestamp (in seconds) of the current block. This is set by the block proposer, and therefore can be manipulated.
@authenticator	text	The registered authenticator name that was used to verify the incoming user.

To use a contextual variable, simply reference it in your SQL statement:

procedure create_user($name text) public {
    INSERT INTO users (name, address)
    VALUES ($name, @caller);
}

Read More

To learn more about Kuneiform and its features, see the section on DDL, which outlines the language features.

To learn more on the supported SQL syntax, check out the full syntax tree.