UATU QL Syntax and Examples

Root Components in UATU QL

UATU QL consists of various root components or elements that make it a powerful and flexible query language. These root components include:

1. Services

2. Functions

3. Filter Blocks

Services

Services, such as Wallet Service and Price Service, provide different functionality based on the available data and user requirements. For instance, a PriceService may offer price-related features like the current price, price history, price alerts, and price comparison.

Functions

Functions perform specific operations or tasks and can be called within a query. For example, the function "get_transactions()" retrieves a list of transactions for a given account or user, or retrieves data related to a specific transaction. Users can input the transaction ID, and the function returns all relevant information, including the sender, receiver, amount, and timestamp.

Filter Blocks

Filter blocks help filter data based on various patterns and requirements. All data is stored in JSON format, and the filter block uses a field, operator, and value to filter the data. Users can filter data using basic SQL queries, such as 'equals,' 'not equals,' 'greater than,' 'less than,' etc. The filter block cannot handle complex queries.

A filter block is composed of several objects, where each object contains three values:

a. Field: Represents the name of the attribute or property in the data that needs to be filtered. b. Operator: Defines the type of comparison to be performed between the field and the value. Some common operators are equals (=), not equals (!=), greater than (>), less than (<), and so on. c. Value: Represents the data that needs to be compared with the field using the operator. The value can be a string, number, boolean, or null.

Example:

// example
{
  "FilterBlock": [
    {"field": "name", "operator": "=", "value": "John"},
    {"field": "age", "operator": ">", "value": 25}
  ]
}

In this example, the filter block is used to filter data where the name is "John" and the age is greater than 25.

Another format of filter block contains various groups of arrays of filter blocks. A filter block is a set of conditions used to filter the data. It can have one or more key-value pairs, where the key represents the field name on which the filtering is to be performed, and the value represents the condition to be checked against the field. Overall, a filter block can be used to filter data based on one or more conditions, and the combiner can be used to combine multiple filter blocks to create more complex filters.

b. Combiner: A logical operator that combines multiple filter blocks to create a more complex filter. The combiner can use logical operators like "AND", "OR", etc., to combine multiple filter blocks.

Example:

{
  "FilterBlock": [
    {
      "combiner": "AND",
      "filterBlock": [
        {"field": "name", "operator": "=", "value": "John"},
        {"field": "age", "operator": ">", "value": 25}
      ]
    },
    {
      "combiner": "OR",
      "filter": [
        {"field": "gender", "operator": "=", "value": "Male"},
        {"field": "gender", "operator": "=", "value": "Female"}
      ]
    }
  ]
}

This is an example of a multiple filter block that uses logical operators to combine multiple filter conditions. The outermost layer contains an array of two filter blocks, each of which has a combiner and another array of filter blocks.

The first filter block in the example uses the "AND" combiner to combine two conditions:

1. The first one checks if the "name" field is equal to "John".

2. The second one checks if the "age" field is greater than 25.

This means that the filter will only return results where both of these conditions are true. The second filter block uses the "OR" combiner to combine two conditions that check if the "gender" field is equal to "Male" or "Female". This means that the filter will return results where either one of these conditions is true. By using logical operators and multiple arrays of filter blocks, complex filtering criteria can be created to precisely select the data that meets specific requirements.

Let's consider a blockchain-specific example:

{
  "FilterBlock": [
    {
      "combiner": "AND",
      "filterBlock": [
        {"field": "tokenSymbol", "operator": "=", "value": "BTC"},
        {"field": "transactionValue", "operator": ">", "value": 1}
      ]
    },
    {
      "combiner": "OR",
      "filter": [
        {"field": "senderAddress", "operator": "=", "value": "0xabc123..."},
        {"field": "receiverAddress", "operator": "=", "value": "0xdef456..."}
      ]
    }
  ]
}

In this example, the filter block filters data based on the following conditions:

1. The token symbol should be "BTC".

2. The transaction value should be greater than 1.

These conditions should both be true. Additionally, either the sender's address should be equal to "0xabc123..." or the receiver's address should be equal to "0xdef456...".

A.2. Sort Blocks

Sort blocks are used to sort data in ascending or descending order. Users can sort data based on a particular field, and the sort block can handle multiple fields. The block also includes options for limit and offset to limit the amount of data retrieved.

Blockchain-specific example:

{
  "SortBlock": [
    {
      "field": "blockTimestamp",
      "sort": "desc"
    }
  ]
}

A.3. Combiners

Combiners are used to combine different filter and sort blocks based on specific conditions. Users can use logical operators like 'AND' and 'OR' to combine different blocks. Combiners allow users to create complex queries and retrieve data based on specific requirements.

Blockchain-specific example:

{
  "Operator": "AND",
  "Filters": [
    {
      "field": "tokenSymbol",
      "Op": "equals",
      "Value": "BTC"
    },
    {
      "field": "transactionValue",
      "Op": "greater_than",
      "Value": 10
    }
  ]
}

A.4. Limit and Offset

Limit and offset are essential tools for handling large amounts of data in UATU QL.

• Limit: Specifies the maximum number of records that should be returned by a query.

• Offset: Specifies how many records should be skipped from the beginning of the query result set.

For example, if you set the limit to 10 and the offset to 5, the query will return the first 10 records that match the specified criteria, starting from the 6th record.

UATU QL Query Examples

Now that we have covered the main components of UATU QL, let's explore some specific examples related to blockchain data:

Example 1: Query transactions of a specific address with a minimum value:

{
  "Filters": [
    {
      "field": "address",
      "operator": "=",
      "value": "0xabc123..."
    },
    {
      "field": "transactionValue",
      "operator": ">",
      "value": 10
    }
  ],
  "SortBlock": [
    {
      "field": "blockTimestamp",
      "sort": "desc"
    }
  ],
  "Limit": 20
}

In this example, we are filtering transactions for a specific address (0xabc123...) with a transaction value greater than 10. The results are sorted in descending order by the block timestamp, and only the 20 most recent transactions are returned.

Example 2: Query token transfers between a pair of addresses:

{
  "Filters": [
    {
      "field": "senderAddress",
      "operator": "=",
      "value": "0xabc123..."
    },
    {
      "field": "receiverAddress",
      "operator": "=",
      "value": "0xdef456..."
    },
    {
      "field": "tokenSymbol",
      "operator": "=",
      "value": "ETH"
    }
  ],
  "SortBlock": [
    {
      "field": "blockTimestamp",
      "sort": "desc"
    }
  ],
  "Limit": 50
}

In this example, we are filtering token transfers of ETH between a pair of addresses (0xabc123... and 0xdef456...). The results are sorted in descending order by the block timestamp, and the 50 most recent transactions are returned.

Example 3: Query top 10 largest transactions within the last 24 hours:

{
  "Filters": [
    {
      "field": "blockTimestamp",
      "operator": ">",
      "value": "timestamp_24_hours_ago"
    }
  ],
  "SortBlock": [
    {
      "field": "transactionValue",
      "sort": "desc"
    }
  ],
  "Limit": 10
}

In this example, we are filtering transactions that occurred within the last 24 hours. The results are sorted in descending order by transaction value, and only the top 10 largest transactions are returned.

These examples demonstrate how UATU QL can be used to create complex queries for retrieving blockchain data based on specific requirements. With its flexible syntax and powerful filtering capabilities, UATU QL enables developers and end-users to efficiently access and analyze blockchain data for various use cases.