YDB Quick Start

In this guide, you will install a single-node local YDB cluster and execute simple queries against your database.

Normally, YDB stores data on multiple SSD/NVMe or HDD raw disk devices without any filesystem. However, for simplicity, this guide emulates disks in RAM or using a file in a regular filesystem. Thus, this setup is unsuitable for any production usage or even benchmarks. See the documentation for DevOps Engineers to learn how to run YDB in a production environment.

Install and start YDB

Run your first "Hello, world!" query

The simplest way to launch your first YDB query is via the built-in web interface. It is launched by default on port 8765 of the YDB server. If you have launched it locally, open localhost:8765 in your web browser. If not, replace localhost with your server's hostname in this URL or use ssh -L 8765:localhost:8765 my-server-hostname-or-ip.example.com to set up port forwarding and still open localhost:8765. You'll see a page like this:

YDB is designed to be a multi-tenant system, with potentially thousands of users working with the same cluster simultaneously. Hence, most logical entities inside a YDB cluster reside in a flexible hierarchical structure more akin to Unix's virtual filesystem rather than a fixed-depth schema you might be familiar with from other database management systems. As you can see, the first level of hierarchy consists of databases running inside a single YDB process that might belong to different tenants. /Root is for system purposes, while /Root/test or /local (depending on the chosen installation method) is a playground created during installation in the previous step. Click on either /Root/test or /local, enter your first query, and hit the "Run" button:

SELECT "Hello, world!"u;

The query returns the greeting, as it is supposed to:

The second simplest way to run a SQL query with YDB is the command line interface (CLI), while most real-world applications will likely communicate with YDB via one of the available software development kits (SDK). Feel free to follow the rest of the guide using either the CLI or one of the SDKs instead of the web UI if you feel comfortable doing so.

Create your first table

The main purpose of database management systems is to store data for later retrieval. As an SQL-based system, YDB's primary abstraction for data storage is a table. To create our first one, run the following query:

CREATE TABLE example
(
    key UInt64,
    value String,
    PRIMARY KEY (key)
);

As you can see, it is a simple key-value table. Let's walk through the query step-by-step:

• Each SQL statement kind like CREATE TABLE has more detailed explanation in YQL reference.
• example is the table name identifier, while key and value are column name identifiers. It is recommended to use simple names for identifiers like these, but if you need one that contains non-trivial symbols, wrap the name in backticks.
• UInt64 and String are data type names. String represents a binary string, and UInt64 is a 64-bit unsigned integer. Thus, our example table stores string values identified by unsigned integer keys. More details about data types.
• PRIMARY KEY is one of the fundamental concepts of SQL that has a significant impact on both application logic and performance. Following the SQL standard, the primary key also implies an unique constraint, meaning the table cannot have multiple rows with equal primary keys. In this example table, it's quite straightforward which column should be chosen as the primary key, which we specify as (key) in round brackets after the respective keyword. In real-world scenarios, tables often have dozens of columns, and primary keys can be compound (consisting of multiple columns in a specified order), making choosing the right primary key more of an art. If you are interested in this topic, there's a guide on choosing the primary key for maximizing performance. YDB tables are required to have a primary key.

Add sample data

Now let's fill our table with some data. The simplest way is to just use literals:

INSERT INTO example (key, value)
VALUES (123, "hello"),
       (321, "world");

Step-by-step walkthrough:

• INSERT INTO is the classic SQL statement for adding new rows to a table. However, it is not the most performant, as according to the SQL standard, it has to check whether the table already has rows with the given primary key values, and raise an error if they exist. Thus, if you run this query multiple times, all attempts except the first will return an error. If your application logic doesn't require this behavior, it is better to use UPSERT INTO instead of INSERT INTO. Upsert (which stands for "update or insert") will blindly write the provided values, overwriting existing rows if there were any. The rest of the syntax will be the same.
• (key, value) specifies the names of the columns we're inserting and their order. The values provided next need to match this specification, both in the number of columns and their data types.
• After the VALUES keyword, there's a list of tuples, each representing a table row. In this example, we have two rows identified by 123 and 321 in the key column, and "hello" and "world" values in the value column, respectively.

To double-check that the rows were indeed added to the table, there's a common query that should return 2 in this case:

SELECT COUNT(*) FROM example;

A few notable details in this one:

• The FROM clause specifies a table to retrieve data from.
• COUNT is an aggregate function that counts the number of values. By default, when there are no other special clauses around, the presence of any aggregate function collapses the result to one row containing aggregates over the whole input data (the example table in this case).
• Asterisk * is a placeholder that normally means "all columns"; thus, COUNT will return the overall row count.

Another common way to fill a table with data is by combining INSERT INTO (or UPSERT INTO) and SELECT. In this case, values to be stored are calculated inside the database instead of being provided by the client as literals. We'll use a slightly more realistic query to demonstrate this:

$subquery = SELECT ListFromRange(1000, 10000) AS keys;

UPSERT INTO example
SELECT
    key,
    CAST(RandomUuid(key) AS String) AS value
FROM $subquery
FLATTEN LIST BY keys AS key

There's quite a lot going on in this query; let's dig into it:

• $subquery is a named expression. This syntax is YQL's extension to the SQL standard that allows making complex queries more readable. It behaves the same as if you wrote that first SELECT inline where $subquery is later used on the last row, but it allows comprehending what's going on piece by piece, like variables in regular programming languages.

• ListFromRange is a function that produces a list of consecutive integers, starting from the value provided in the first argument and ending with the value provided in the second argument. There's also a third optional argument that can allow skipping integers with a specified step, but we omit it in our example, which defaults to returning all integers in the given range. List is one of the most common container data types.

• AS is a keyword used to give a name to the value we're returning from SELECT; in this example, keys.

• FROM ... FLATTEN LIST BY ... AS ... has a few notable things happening:

  • Another SELECT used in the FROM clause is called a subquery. That's why we chose this name for our $subquery named expression, but we could have chosen something more meaningful to explain what it is. Subqueries normally aren't materialized; they just pass the output of one SELECT to the input of another on the fly. They can be used as a means to produce arbitrarily complex execution graphs, especially if used in conjunction with other YQL features.
  • FLATTEN LIST BY clause modifies input passed via FROM in the following way: for each row in the input data, it takes a column of list data type and produces multiple rows according to the number of elements in that list. Normally, that list column is replaced by the column with the current single element, but the AS keyword in this context allows access to both the whole list (under the original name) and the current element (under the name specified after AS), or just to make it more clear what is what, like in this example.

• RandomUuid is a function that returns a pseudorandom UUID version 4. Unlike most other functions, it doesn't actually use what is passed as an argument (the key column); instead, it indicates that we need to call the function on each row. See the reference for more examples of how this works.

• CAST(... AS ...) is a common function for converting values to a specified data type. In this context, the type specification is expected after AS (in this case, String), not an arbitrary name.

• UPSERT INTO will blindly write the values to the specified tables, as we discussed previously. Note that it didn't require (key, value) column names specification when used in conjunction with SELECT, as now columns can just be matched by names returned from SELECT.

Stop the cluster

Stop the local YDB cluster after you have finished experimenting:

~/ydbd/stop.sh

docker kill ydb-local

kubectl delete database.ydb.tech database-minikube-sample

kubectl delete storage.ydb.tech storage-minikube-sample

helm delete ydb-operator

kubectl delete database.ydb.tech database-kind-sample

kubectl delete storage.ydb.tech storage-kind-sample

helm delete ydb-operator

kind delete cluster

Done! What's next?

After getting a hold of some basics demonstrated in this guide, you should be ready to jump into more advanced topics. Choose what looks the most relevant depending on your use case and role:

• Walk through a more detailed YQL tutorial that focuses on writing queries.
• Try to build your first app storing data in YDB using one of the SDKs.
• Learn how to set up a production-ready deployment of YDB.
• Read about YDB concepts.