Querying

Once the data is indexed and available in your tables, it is time to query it. It was already mentioned there are two ways of doing that, and they are:

• Utilize our GraphQL API, which offers standardized queries and returns data in base64 XDR format.

• Call a Zephyr serverless function where you can customize various aspects, including the response format.

With GraphQL API

This is the most straightforward way of querying Zephyr's data. You just have to craft a request and send it to our GraphQL API. Testnet and Mainnet endpoints can be found in the endpoints section. From the Zephyr dashboard, you have to find the name of the table to want to query and insert it in the request body.

Following the example on the quickstart, to request the data on our table zephyr_85b036892719b0a99aa987b1f62e9b10, the query will look like this:

query Test {
  allZephyr85B036892719B0A99Aa987B1F62E9B10S {
    edges {
      node {
        hello
      }
    }
  }
}

Under "node" make sure to insert the names of the table's columns you need to query.

In this early release version of Zephyr, please note that to correctly craft the query, you need to change the table name you insert in the following way:

• Add "All" in front of the table name and write "Zephyr" with capital Z.

• Eliminate the underscore and put all letters in the table name as capitals.

Ex: zephyr_6867876d691836698b268c62c09024e9 → allZephyr6867876D691836698B268C62C09024E9S

It is also important to note that up to now it's not possible to customize the tables' names. You will have to remember them or explore the table structure in the playground (under "nodes" you can find the different columns) to find the right table.

The request will be the following:

curl 'https://api.mercurydata.app/graphql' \
  -H 'authorization: Bearer YOUR_JWT' \
  -H 'content-type: application/json' \
  --data-raw '{"query":"query Test {\n  allZephyr85B036892719B0A99Aa987B1F62E9B10S {\n    edges {\n      node {\n        hello\n      }\n    }\n  }\n}\n","operationName":"Test"}' \
  --compressed

Note that here we're querying the Testnet endpoint. Make sure to call the right API.

GraphQL Playground

It is also possible to use the GraphQL playground to perform your queries (you can find it in the endpoints section). It could be particularly useful especially when you start understanding Zephyr, and for crafting the queries.

Just remember, before sending the request from the playground, to put your Mercury access token in the authentication headers. An example of how to use the playground can be found in this Mercury's tutorial.

Handling the Response

What you get as a response will be base-64 XDR encoded and look like this:

{
  "data": {
    "allZephyr85B036892719B0A99Aa987B1F62E9B10S": {
      "edges": [
        {
          "node": {
            "hello": "AAAADgAAACBXb3JsZCBhdCBsZWRlZ3Igc2VxdWVuY2UgMTMxMTY5Nw=="
          }
        },
        {
          "node": {
            "hello": "AAAADgAAACBXb3JsZCBhdCBsZWRlZ3Igc2VxdWVuY2UgMTMxMTY5OA=="
          }
        },
        ...
      ]
    }
  }
}

Here you can see all the contents of the table's column "hello". To decode the data we can use the Stellar Laboratory (in this case we have saved the data as ScVals).

To better understand how to decode the return types on your client, you can jump to the "work with data structures" section.

With Serverless Functions

This approach requires a bit more work at the beginning but is the best and most efficient choice for querying data as it allows you to work with Soroban data structures from the program using the Soroban and Rust type system.

That means that after calling the function from the client, your data will be returned directly in the format you decide. To create these customized endpoints, a better and more technical explanation of serverless functions is required.

To learn how to create your custom API endpoints using serverless functions, go to the serverless functions section.