Macrometa GDN | Query Workers

Introduction to Query Workers

Query workers are named and parameterized C8QL queries stored in the Macrometa GDN. They can be executed from a dedicated REST endpoint, and are also known as RESTQL or “Query as API”. 

Macrometa’s query workers are written using C8 Query Language, also known as C8QL. The bind vars, query parameters, are created by using an '@' symbol in front of a literal value. This allows for the separation of the query text and the literal values. More information about using bind vars can be found here, https://macrometa.com/docs/c8ql/fundamentals/#bind-parameters.  

After being saved to the GDN, a query worker is automatically converted to a global API endpoint which serves users from the region closest to them at local latencies.

 

Working with Query Workers

To begin using query workers in the GDN Console, navigate to the Queries section in the sidebar.

Click to open the image in a new tab.

 

The Queries section opens an editor window. The user can write a query to save as a query worker here. Bind vars, created with the '@' symbol, will display fields for the corresponding Key and Value on the right-hand side. You can use this to pass values to your query or query worker in the Query Editor.

Click to open the image in a new tab.

 

For the purpose of this article, we will be using the following query.

FOR i IN DocumentCollection
FILTER i.key1 == @value
RETURN i.key1

This query accepts one bind var, @value, and returns any records matching the value from the collection named “DocumentCollection”. 

 

Run Query:

We can execute the query inside the editor window by clicking the "Run Query" button or pressing return + command. Results are returned in the "Query Result" pane below the editor.

Click to open the image in a new tab.

API endpoint:

Shows the cURL (Client URL) command which can be used in the terminal or command line to make an API call to execute the query worker.

Click to open the image in a new tab.

 

Execution Plan:

Shows a detailed breakdown of the query compilation and execution pipeline.

Details given can also be helpful when tuning or debugging complex queries.

Click to open the image in a new tab.

 

Save Query:

To complete the creation of the query worker click "Save Query". Query Workers are saved with a custom name, let’s save our query as “queryWorker”. When you save your Query Worker a new option, “Update Query”, will appear. Use this to save changes to existing Query Workers.

Click to open the image in a new tab.

 

Let's proceed to saved queries and see how we can use our new Query Worker.

Saved Queries:

This section displays the saved queries. We can choose to copy, explain, run or delete the query. 

Note: For query workers that are pre-built in the system, copy query is the only action.

Click to open the image in a new tab.

 

Actions:

Navigate through the “Name” list to find the relevant query, in our case “queryWorker”.

Following is a list of actions we can perform on the selected query:

Copy Query
This action will allow us to edit Query Worker in the query editor.

Explain Query
This action will give an execution plan of a Query Worker without actually executing the query.

Run Query
This action will run Query Worker and provide query results. The result will be posted in the result box. If we run multiple queries we can compare results easily. We also have additional information, the number of results, query running time, and Query Profile.

Delete Query - This action will delete the Query Worker worker from GDN.

Query Builder:

Opens the editor window where the user can create a new Query Worker.

Import Queries:

Allows us to import queries into the query editor window and then save them as a Query Worker. The imported document must be in JSON format.

Click to open the image in a new tab.

Export Queries:

Allows exporting Query Worker (in JSON format).

 

Conclusion

Macrometa Query Workers provide a fast and flexible way to create dedicated REST endpoints. This enables the development of a safe and secure backend for your applications with speed. 

 

Documentation Resources:

https://macrometa.com/docs/c8ql/introduction/
https://macrometa.com/docs/c8ql/fundamentals/#bind-parameters
https://macrometa.com/docs/restql/concepts/