Skip to main content

Basic queries

This section introduces the fundamentals of working with queries in Chromia blockchain development. Queries are essential for retrieving data from the blockchain, and you will learn to create and test them step by step.

In our dapp, you need queries to:

  1. Display the username of a user.
  2. Count how many followers a user has.
  3. Count how many users a user is following.
  4. Check if one user follows another.
  5. Retrieve a list of posts.
  6. Show all users.

Here's how to create and use queries in Chromia:

User and follower queries​

You define queries as functions using the query keyword. Let’s start by creating a query to get a uniquely identifiable username:

rell/src/news_feed/queries.rell
query get_user_name(user_id: byte_array): text {
  return user @ { user_id } ("%s#%s".format(.name, .id.to_hex().sub(0, 5)));
}

This query retrieves a user and formats a text string by concatenating the name and the first five characters of the hex representation of the ID. Next, we will create two queries to count followers and the users a given user follows.

rell/src/news_feed/queries.rell
query get_followers_count(user_id: byte_array): integer {
  return follower @ { .user == user @ { user_id } } (@sum 1);
}

query get_following_count(user_id: byte_array): integer {
  return follower @ { .follower == user @ { user_id } } (@sum 1);
}

These queries are similar but differ in how they filter results from the follower database query. You can omit the return type integer because Rell can deduce it from the return statement, allowing us to simplify the queries as follows:

query get_followers_count(user_id: byte_array) =
  follower @ { .user == user @ { user_id } } (@sum 1);

You can also create a query to check if a follower entity exists as follows:

rell/src/news_feed/queries.rell
query is_following(my_id: byte_array, your_id: byte_array) =
  exists(follower @? { .user.id == your_id, .follower.id == my_id });

Query posts with pagination​

Next, you will create a query to retrieve posts created by users that a specific user follows. Since this may return a large number of posts, pagination is necessary to manage the data effectively. Make sure to order the results from the latest to the oldest posts.

To manage post data efficiently, define a struct called post_dto:

src/main.rell
struct post_dto {
  timestamp;
  user: struct<user>;
  content: text;
}

This structure resembles a post entity, but the user field has a slightly different format. The type [struct<T>] (https://docs.chromia.com/rell/language-features/modules/struct#structmutable-t) is an in-memory representation of an entity, meaning that all fields are loaded into memory for efficient use.

Retrieve posts​

To retrieve the desired posts, you will join tables, filter data, and add pagination:

rell/src/news_feed/queries.rell
query get_posts(
  user_id: byte_array,
  pointer: integer,
  n_posts: integer
): (pointer: integer, posts: list<post_dto>) {
  val posts = (user, follower, post) @* {
    user.id == user_id,
    follower.follower == user,
    post.user == follower.user
  } (
    @sort_desc @omit post.rowid,
    post_dto(
        post.timestamp,
        post.content,
        user = post.user.to_struct()
    )
  ) offset pointer limit n_posts;

  return (
    pointer = pointer + posts.size(),
    posts = posts
  );
}

Here’s what happens in this query:

  • You specify the user whose followers' posts you want to retrieve using user_id.
  • You join the user, follower, and post tables to obtain the necessary data.
  • You sort the posts in descending order based on their creation timestamp to retrieve the latest posts first.
  • You create a post_dto data structure for each post, including the user's structured representation.
  • You include an offset to skip posts and a limit to control how many posts to retrieve.

In the database query, you sort posts in descending order to fetch the latest ones first, although this detail is omitted from the resulting data structure. While you could paginate based on timestamps, this method simplifies the process.

Return results​

Finally, you return the results as a named tuple with two components:

  • pointer: An index indicating where to start the next query.
  • posts: A list of post_dto objects containing the retrieved posts.

This approach allows you to create simple data structures without explicitly defining dto structs.

With this query, you can efficiently fetch posts created by a user's followers with pagination, simplifying the management and display of data in your dapp.

Query user list​

To retrieve all users in the dapp, we need a query that combines elements from the get_user_name query and pagination from get_posts. The following query accomplishes this:

rell/src/news_feed/queries.rell
query get_users(pointer: integer, n_users: integer) {
  val users = user @* {} (name = "%s#%s".format(.name, .id.to_hex().sub(0, 5)), id = .id) offset pointer limit n_users;
  return (
    pointer = pointer + users.size(),
    users = users
  );
}

Test the queries​

We can now test these queries to ensure they function as expected. We begin with a simple test case for the get_user_name query:

src/test/my_news_feed_test.rell
function test_user_name() {
    rell.test.tx()
        .op(create_user("Alice", alice))
        .run();
    assert_equals(get_user_name(alice), "Alice#02466");
    val users_result = get_users(0, 20);
    assert_equals(users_result.pointer, 1);
    assert_equals(users_result.users.size(), 1);
    assert_true(users_result.users @* {} (.name).contains("Alice#02466"));
}

In this example, the @-operator successfully operates on lists.

Next, we will assess the follower count through another test case:

src/test/my_news_feed_test.rell
val charlie = rell.test.pubkeys.charlie;

function test_follower_calculation() {
    rell.test.tx()
        .op(create_user("Alice", alice))
        .op(create_user("Bob", bob))
        .op(create_user("Charlie", charlie))
        .run();

    rell.test.tx()
        .op(follow_user(alice, bob))
        .op(follow_user(alice, charlie))
        .run();

    assert_true(is_following(alice, bob));
    assert_true(is_following(alice, charlie));
    assert_equals(get_following_count(alice), 2);
    assert_equals(get_following_count(bob), 0);

    assert_equals(get_followers_count(alice), 0);
    assert_equals(get_followers_count(bob), 1);
}

In this test case:

  • We create three users: Alice, Bob, and Charlie.
  • Alice follows both Bob and Charlie.
  • We use assert_equals to verify that the queries return the correct follower and following counts.

Test pagination for posts​

Next, we will test the pagination feature for retrieving posts. This test case will involve creating users, having them follow each other, and then creating posts.

src/test/my_news_feed_test.rell
function test_pagination_of_posts() {
    rell.test.tx()
        .op(create_user("Alice", alice))
        .op(create_user("Bob", bob))
        .run();
    rell.test.tx().op(follow_user(alice, bob)).run();

    for (i in range(5)) {
        rell.test.tx().op(make_post(bob, "Content %d".format(i))).run();
    }

    val initial_posts = get_posts(alice, 0, 4);
    assert_equals(initial_posts.pointer, 4);
    assert_equals(initial_posts.posts.size(), 4);
    val last_posts = get_posts(alice, initial_posts.pointer, 4);
    assert_equals(last_posts.pointer, 5);
    assert_equals(last_posts.posts.size(), 1);
}

In this test case:

  • We create users Alice and Bob.
  • Alice follows Bob.
  • Bob creates five posts.
  • We use pagination to retrieve posts and verify if the results align with expectations.

Manually test the dapp​

In addition to automated tests, you can manually test your dapp by running a local test node and interacting with it using the Chromia CLI.

Start a test node​

To start a local test node, execute the following command from your project folder:

chr node start

Monitor the logs as the node progresses to build blocks.

Create users and transactions​

To create users, generate public keys using the chr keygen command. For this tutorial, we'll use the following public keys for Alice and Bob:

  • Alice: 03854EAE78096078DB97B18E8900DA5518613F5460F3D49C1F52B0223CBB9BC114
  • Bob: 0389F8109AF5D6670E96B49C6FE5FE2E62D793D948D6FB9138DEFD2A13C3B351D9

To create Alice as a new user, run:

chr tx --await create_user Alice 'x"03854EAE78096078DB97B18E8900DA5518613F5460F3D49C1F52B0223CBB9BC114"'

You'll see confirmation with a message like:

Transaction with rid TxRid(rid=9042157A8C2DC4B8C974510540067C7367DEE1AEC7FCE9BBF5FB6D6E0DC37F3C) was posted CONFIRMED

Next, create Bob with the command:

chr tx --await create_user Bob 'x"0389F8109AF5D6670E96B49C6FE5FE2E62D793D948D6FB9138DEFD2A13C3B351D9"'

You will receive another confirmation:

Transaction with rid TxRid(rid=D74C829485EB1BB0A5DB39374067C2B5B53A92CF072D76B25624DD01908CC300) was posted CONFIRMED

After this, have Alice follow Bob and create a post for Bob:

chr tx --await follow_user 'x"03854EAE78096078DB97B18E8900DA5518613F5460F3D49C1F52B0223CBB9BC114"' 'x"0389F8109AF5D6670E96B49C6FE5FE2E62D793D948D6FB9138DEFD2A13C3B351D9"'

You will see:

Transaction with rid TxRid(rid=F5BC2D5C9979EFE0E91CF39A605DCD4E36235CB98CBE33EB661E595C99DF7A63) was posted CONFIRMED

Finally, create a post for Bob with the command:

chr tx --await make_post 'x"0389F8109AF5D6670E96B49C6FE5FE2E62D793D948D6FB9138DEFD2A13C3B351D9"' "My first post"

You'll see confirmation with a message like:

transaction with rid TxRid(rid=5686A5AD5FD2E15CAA29EF2BA1C687BD725ADABEAE323296374F212685A9AEA3) was posted CONFIRMED

Test queries​

You can now test your queries manually using the Chromia CLI. Here are a few examples:

chr query get_following_count 'user_id=x"03854EAE78096078DB97B18E8900DA5518613F5460F3D49C1F52B0223CBB9BC114"'

This command returns the number of users that Alice follows:

1

chr query get_followers_count 'user_id=x"03854EAE78096078DB97B18E8900DA5518613F5460F3D49C1F52B0223CBB9BC114"'

This command fetches the number of users following Alice:

0

chr query get_posts user_id='x"03854EAE78096078DB97B18E8900DA5518613F5460F3D49C1F52B0223CBB9BC114"' pointer=0 n_posts=10

This command retrieves the posts made by Alice:

{
  "pointer": 1,
  "posts": [
    {
      "content": "My first post",
      "timestamp": 1694073942456,
      "user": {
        "name": "Bob",
        "id": "x\"0389F8109AF5D6670E96B49C6FE5FE2E62D793D948D6FB9138DEFD2A13C3B351D9\""
      }
    }
  ]
}

In this query, you can see the details of the post that Alice created for Bob.

Congratulations! You’ve successfully completed the first module of this course. In the next module, you will gain deeper insights into validating user input in operations and securing transactions against impersonation. Stay tuned!