Query API

BASIC EXAMPLE

All of the queryable can be found under the DOCS tab on the right side of the playground (https://mainnet.tezgraph.tez.ie/graphql).

In this example, we are querying for the hash and batch_position of the two latest (first) transaction records with the public key hash tz1MBidfvWhJ64MuJapKExcP5SV4HQWyiJwS as the source.

The accounts query takes a filter argument. Inside this filter argument is an addresses field of type [Address!]. Here inside this array is where we insert our target addresses. The public key hashes of both implicit and originated accounts are accepted as valid addresses.

The accounts query also requires either the argument first or last. In this example we are using first: 1. In the case of the accounts query, the first and last arguments determine which of the addresses provided in filter.addresses (filter: { addresses: ["..."]}) will be used in the query. If first: 3 is used, Tezgraph would then only return results for the first 3 addresses in from filter.addresses.

Inside accounts, we using an edges sub-selection. Edges consist of two fields, cursor and node. The node field is a sub-selection where we request the fields of interest.

Inside the accounts.edges.node query, we are sub-selecting transaction records using operations. operations can also take in arguments such as first, last, order_by, before, after, filter, and order_by.

By default, the TezGraph Query API returns all records in descending chronological order. This means that the first record in the list would be the latest, and the last record would be the oldest. This sorting order may be modified with the argument order_by, which will be explained in the Advanced Example.

Here we are using the argument first: 2. Since we are using the default sort order, which is in descending chronological order, it will return the two latest transaction records from the account.

Inside operations, you can see we are using edges, node, and cursor as well. The cursor field is used for pagination, which will be explained in the Pagination Example.

ADVANCED EXAMPLE

In this example, we are querying for the hash, batch_position, internal, and timestamp of transaction records with the public key hash (address) of tz1MBidfvWhJ64MuJapKExcP5SV4HQWyiJwS as the source.

In this example, we have added the order_by and filter.timestamp arguments.

  • order_by: { field: chronological_order, direction: asc } - This argument will order the records in ascending (asc) chronological order.
  • first: 10 - Since we are ordering the operations in ascending chronological order, this argument will return the ten oldest records, with the oldest record at the top and the later record at the bottom.
  • filter.timestamp: { gte: "2019-06-13T16:22:03Z", lte: "2019-06-14T16:22:03Z" } - This argument will only return the records with a timestamp less than or equal to 2019-06-14T16:22:03Z and greater than or equal to 2019-06-13T16:22:03Z.

PAGINATION EXAMPLE

In this example, we are querying for the hash, batch_position, internal, and timestamp of the two latest (first) transaction record with the public key hash of tz1MBidfvWhJ64MuJapKExcP5SV4HQWyiJwS as the source. In addition, we have also added the cursor field to the edges sub-selection.

The cursor field in the edges sub-selection returns a string made up of the operation's hash, batch_position, and internal values separated by a :. This unique string is used for pagination.

Using the cursor of a record, we can query for the records before or after the record that the cursor references.

To do this, we use the arguments before or after, along with the arguments first or last.

  • Pagination requires the use of one of the before and after arguments and one of the first or last arguments.

The following pagination queries will succeed:

  • first: 2, after: "opNxsLZeNMttsyh4PxLk35dmRsJyLXQwJjpVp89ip7pU2j5yzyR:0:0"
  • last: 20, before: "opNxsLZeNMttsyh4PxLk35dmRsJyLXQwJjpVp89ip7pU2j5yzyR:0:0"

The following pagination queries will fail:

  • first: 100, last: 100, after: "opNxsLZeNMttsyh4PxLk35dmRsJyLXQwJjpVp89ip7pU2j5yzyR:0:0"
  • last: 100, before: "opEHTGa4n4efFQfpaWFNqoY4dbzXrBEo7Xo8v74AX5pEREqK28S:0:1", after: "opNxsLZeNMttsyh4PxLk35dmRsJyLXQwJjpVp89ip7pU2j5yzyR:0:0"

In this pagination example, we are querying for the first ten records after the first record in the Basic Example Results. We do this by using the following arguments:

  • after: "opNxsLZeNMttsyh4PxLk35dmRsJyLXQwJjpVp89ip7pU2j5yzyR:0:0" - With this argument, the results will only return records after the record this cursor references.
  • first: 10 - Since we are using the default sort order, which is in descending chronological order, it will return the two latest transaction records after the record that the above cursor references.

The results should show that the first record from this example is the second record from the Basic Example Results.