When you are putting data into Ardoq you are essentially building up an Enterprise Intelligence Graph. This provides an always up-to-date Digital Twin of all data, processes, and their relationships, meaning you can ask the system about all parts of your documentation.
We use the graph traversal language Gremlin (external article) to write queries in Ardoq. This helps you navigate the vertices and edges of your Enterprise Intelligence Graph.
Tip: Use our selection of common queries as inspiration to build your own based on your data sets.
Table of contents:
Before Getting Started
To create Gremlin queries, you must have the "Create Gremlin" privilege enabled. It is possible to enable privileges on a user role or individually per user.
⚠️ IMPORTANT: The Gremlin privilege permits Writer users to view data in the entire graph, ignoring existing workspace permissions. It should ONLY be enabled for users with high trust. For example, users who might have otherwise had the Admin role but who can now accomplish their responsibilities as Writers with Gremlin access.
How to Allow Users to Create Gremlin Queries
Given that you are an admin user in the Ardoq app, you can allow users to create Gremlin queries by enabling the “Create Gremlin” privilege on their user role or individually per user.
How to Enable The “Create Gremlin” Privilege on a User Role
To allow all users with a specific user role to create Gremlin queries:
Navigate to Preferences > Organization Settings > Manage User Roles
Select the user role you want to configure
Tick the “Create Gremlin” checkbox
Click “Save”
Enabling the “Create Gremlin” privilege on a user role is the easiest way to manage who can create Gremlin queries in your organization. Once the “Create Gremlin” privilege is enabled on a user role, it is not possible to disable it on specific users who have that user role.
For example, if you enable the “Create Gremlin” privilege on the Writer user role, all of your existing Writer users, and those you add in the future, will be able to create Gremlin queries. Because the “Create Gremlin” privilege is enabled on the Writer user role, you won’t be able to disable the “Create Gremlin” privilege on single users who have the Writer user role assigned.
How to Enable the “Create Gremlin” Privilege per Single User
Enable the “Create Gremlin” privilege individually per user when you need certain people to create Gremlin queries and their user role does not allow them to.
To enable the “Create Gremlin” privilege on single users:
Navigate to Preference > Organization Settings > Manage Users
Look for the user you want to enable the “Create Gremlin” privilege on
Click on the three-dot menu next to the name of a user and select "Assign privileges"
Select "Create Gremlin" from the dropdown
Hit "Save"
How to Create a Gremlin Query
You can query your data by:
Creating a quick Gremlin search from the Analytics menu > Gremlin Graph Search. To save your query you will need to save it as a report.
Creating a Gremlin Graph search report. To create a report, navigate to the Home page and select "Create new > Report" at the top right corner of the screen or navigate to the Analytics menu > Report Overview > Create new.
Next:
Select "Gremlin Graph Search" in the "Data selection" section of the Report Builder.
Choose the workspace(s) you wish to query.
Write your Gremlin query.
In the example below, we are asking what applications are affected if a certain server is crashing:
g.V().
has("name", "mongodb-1").
both(). hasLabel('Application').
dedup()
You can see the results in the "Preview search results" modal or in the "Data presentation" section of the Report Builder:
Save your report to save your query. You can then find it by filtering the Home page by "Reports" or in the "Reports overview" page.
Note that this can be a bit confusing if you are new to Gremlin, so please don't hesitate to reach out for more information and help with queries.
Manage Queries
To manage your reports, navigate to the Analytics menu > Report overview. Alternative, head to the Home page and filter by "Reports".
In addition to this, you can load reports in a Dashboard for a simpler view of more reports at once. To find the Dashboards, navigate to the Analytics menu > Dashboard overview or to the Home page and filter by "Dashboards".
Click edit dashboard or create a new one from the Home page > Create new > Dashboard, and add the reports you want to display. For now, you can choose between showing the number of results over time or the total number of results. Click on View details to see more:
FAQ
Where can I learn more about Gremlin?
For advanced understanding of Gremlin language, please refer to Tinkerpop documentation.
Ardoq reserved fields and how to call them using gremlin.
