Adding structured results from queries

In this section, we'll learn how to structure the results from queries in Chromia. This approach can be beneficial when you need to fetch complex data, such as combining book information with associated reviews.

To achieve this, we'll create a book_review_dto struct to encapsulate the book details and the review information. We'll then update our query to return this structured data.

Define the struct

We will define a new struct, book_review_dto, which will contain the book information and review details. This struct should be added to the src/main/entities.rell file, which is appropriate for defining such data structures.

Open the src/main/entities.rell file and add the following code:

src/main/entities.rell

struct book_review_dto {
  book: struct<book>;
  reviewer_name: text;
  review: text;
  rating: integer;
}

Update the query

Next, we'll modify the get_all_reviews_for_book query to use the book_review_dto struct. This will allow us to include both book and review information in a single query result.

Open the src/main/queries.rell file and update the query as follows:

src/main/queries.rell

query get_all_reviews_for_book(isbn: text) {
  require(book @? { .isbn == isbn }, "Book with isbn %s not found".format(isbn));
  val reviews = book_review @* { .book.isbn == isbn } (
    book_review_dto(
      book = .book.to_struct(),
      .reviewer_name,
      .review,
      .rating
    )
  );
  return reviews;
}

Explanation

1. Struct Definition: The book_review_dto struct combines the book and review details into a single unit, making it easier to manage related information together.

2. Updated Query:

   • The require function checks that the book with the specified isbn exists.
   • The query book_review @* { .book.isbn == isbn } fetches all reviews for the specified book.
   • We use the book_review_dto struct to structure the result. The book attribute of the struct is populated using book_review.book.to_struct() converts the book field into a structured format.

Testing the update

To ensure that everything is working as expected, follow these steps:

1. Update the node:

   If you have a Chromia node running, update it with the latest version of your dapp:

   chr node update

   If the node is not running, start it with:

   chr node start
   note

   If you update the node while it is running, it might take a moment for the changes to propagate. You may need to wait for the next block for the update to be fully effective.

2. Run the query:

   Execute the query using the Chromia CLI:

   chr query get_all_reviews_for_book "isbn=ISBN1234"

   The expected output should look something like this:

   [
     {
       "book": {
         "author": "George Orwell",
         "isbn": "ISBN1234",
         "title": "1984"
       },
       "rating": 5,
       "review": "It was a great book",
       "reviewer_name": "Alice"
     }
   ]

Summary

In this lesson, we added a book_review_dto struct to combine book and review details into a structured format. We updated the query to return this structured data, making it easier to handle and display in client applications. This approach improves the organization and usability of the data you retrieve from the blockchain.