Calculated fields in Ardoq make it possible to collect and process information across everything you have documented in Ardoq. They allow you to store the result as a field value on components and references. The calculated field value is read-only but it behaves like any other field in Ardoq. They can be used for filtering, grouping, and conditional formatting.
For example, in our Application Portfolio Management best practice module, we use a calculated field to weight and sum the six underlying dimensions for business and technical fit into two dimensions for display in a Gartner TIME quadrant. In our upcoming Risk analysis, the risk score will be based on calculated fields.
All calculations are scheduled to run hourly. You can also trigger calculations manually via the:
Calculation editor (Preferences > Organization settings > Manage fields > Edit calculation)
Workspace options in the sidebar menu (☰ > Workspace tab > Recalculate field values)
Ardoq API. For example, by setting up a Zapier zap to trigger the recalculate endpoint as often as you wish.
Table Of Contents:
How to Create a Calculated Field
⚠️ Some points to consider before proceeding:
Calculated fields use Gremlin graph queries:
Make sure you have the "Create Gremlin queries" privilege enabled.
Learn about Graph search to run powerful data analysis. You can also copy/paste the examples below if you find something that is close to what you're trying to achieve.
Since calculated fields are based on graph queries, and these have access to the whole graph, you need to be an Ardoq organization-admin user to configure calculated fields.
Step 1: Create the field
Open a workspace from the Home page.
Next, open the sidebar menu (☰) on the right.
Navigate to the "Workspace" tab > "Manage Field Types".
Click "Add Field" and select a field that is a calculated field from the dropdown. Alternatively, type in a new name and hit enter to create a new field.
Next, choose a field of type calculated from the bottom of the 'Type' dropdown.
Specify if the calculated field should apply to all component and reference types in the workspace or only to a few of them.
Select the "Create & edit" button. You will be taken to the Gremlin query editor.
Step 2: Edit the query
When creating a new calculated field, you will be taken to the Gremlin query editor where you can enter and test your query. You can also edit existing calculated field queries from here.
There are two ways in which you can access the Gremlin query editor to modify current calculated field queries:
From the sidebar menu (☰) when in a workspace:
Open a workspace
Click on the sidebar menu (☰) icon at the top right corner of the screen
Navigate to the Workspace tab and select "Manage fields"
Find the calculated field you want to update and click on the "Edit" button
Next, scroll down all the way to the bottom of the sidebar and select "Edit calculation"
From the Preferences menu:
Go to Preferences > Organization settings > Manage fields.
Locate the calculated field you created in step 1.
Click on the edit pen icon to modify the calculation.
Calculations are performed in the Ardoq Graph Engine and are programmed in the graph query language Gremlin.
*Note: All calculated field queries have the first line injected with an array of all the IDs of the components or references the field applies to. This serves as a starting point for the traversal.
It is recommended to not modify the code on lines 0 to 4 shown above. Because the calculations are expected to be in the format seen below, you typically only need to modify the last line (the value-calculation).
Calculated fields expect a return value of this shape:
[
{"id": "<component-id-1>", "value":1},
{"id": "<component-id-2>", "value":2}
]
Step 3: Test, save and apply the query
Once you've modified the query to your liking, test the calculation. If there are no warnings, click the 'Apply calculation' button to save it. Then exit the editor.
The calculation will run every hour. You can also can trigger it from the Workspace sidebar when the workspace is open.
Example queries
This example uses a function to calculate risk, using an existing "risk factor" value for components:
def riskCalculator = {
component = it.get()
if (component.property("risk_factor").isPresent()) {
component.property("risk_factor").value() > 5 ? "high" : "low"
} else {
"none"
}
}
g.V(ids)
.project('id', 'name', 'value')
.by(id)
.by('name')
.by(map(riskCalculator))This example aggregates cost one level up to the components the calculated field applies to (in this case we set the field to apply to Applications), showing graph traversals can be performed:
g.V(ids).
project('id', 'name', 'value').
by(id).
by('name').
by(inE().hasLabel('Relates to').otherV().values("cost").sum())
The following example provides a more flexible query that traverses the graph, collecting the cost of all components encountered along the way. Here we only go in one reference-direction, meaning components must have an outgoing reference towards the component that has this calculated field:
g.V(ids).
project('id', 'name', 'value').
by(id).
by('name').
by(emit().repeat( // Emit includes all components encountered
inE().otherV()
).timeLimit(1000).dedup() // remove duplicate components
.values("cost").sum() // sum up cost of all found components
)
The following is an example of a calculated URL field. It's value will be a URL that is the same as the URL of the component's overview page in Discover.
g.V(ids).
project('id', 'name', 'value').
by(id).
by('name').
by(map{'https://myenvironment.ardoq.com/discover/overview/' + it.get().id()})
You will just need to make sure to change 'myenvironment.ardoq.com' to your own Organization's domain.
FAQ
What is the "ids"-value used for?
The "ids"-value is automatically generated and contains the unique ids of all components and/or references the calculated field is set to apply to. This means that you can modify the field so that it applies to a different set of references or components, without modifying the query.
Why are my calculated fields not showing in the "editor/views"?
This is likely because of values returned by the query. Calculated number-fields, for example, expects a number to be returned. For instance, this query for a calculated number will fail:
[
{"id": "fb3f69b7798", "value": 1234}, <--- OK, NUMBER 👍
{"id": "86e95ce6b5c", "value": "high"}, <--- NOT A NUMBER 👎
]
Please ensure all values returned match the field type (calculated number, calculated text, calculated date time, calculated checkbox (boolean))!
Can I reuse the calculated field?
By "reuse", we mean modifying the field to apply to new component or reference types. This is possible, but if you want to do so, you must ensure that the query is not too specific. For example, if the query is written to traverse the graph via specific reference types, the query might not work for other component types that don't have connections using the same reference type.
Why is the 'Apply Calculation' button grayed out?
This is because the query that was previously stored hasn't undergone any changes. The button will turn on and be clickable as soon as the code is altered.
Why is my calculated query missing/deleted?
If the field the calculated query is connected to is removed, the query will also be deleted.
Question: How can I find which components a calculated field is associated with, and why can't I see calculated fields in the component properties?
Calculated fields won’t appear when you edit the properties of a component directly. Instead, they are visible in the sidebar menu under the "Calculated fields" section for the entire workspace.
To identify which components a calculated field is associated with:
Open the sidebar menu for the workspace and scroll down to the "Calculated fields" section to see all calculated fields that have been added.
To manage and edit calculated fields or see which component types they apply to, go to Workspace > Manage field types from the sidebar menu.
From here, select the calculated field you want to edit, and you will see which component types it applies to in the field properties.
To Summarize: Calculated fields are applied at a broader scope and are not directly editable at the individual component level, which is why they do not appear in the component’s property editor.