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.
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.
For the purpose of this article, we will be using the following query.
FOR i IN DocumentCollection
FILTER i.key1 == @value
This query accepts one bind var, @value, and returns any records matching the value from the collection named “DocumentCollection”.
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.
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.
Shows a detailed breakdown of the query compilation and execution pipeline.
Details given can also be helpful when tuning or debugging complex queries.
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.
Let's proceed to saved queries and see how we can use our new Query Worker.
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.
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:
This action will allow us to edit Query Worker in the query editor.
This action will give an execution plan of a Query Worker without actually executing the 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.
Opens the editor window where the user can create a new Query Worker.
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.
Allows exporting Query Worker (in JSON format).
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.