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 nightly. 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:


Setting up a calculated field

⚠️ Some points to consider before proceeding:

  • Creating a calculated field involves Gremlin graph queries code. Learn more 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 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 number field from the dropdown. Alternatively, type in a new name and hit enter to create a new field. Next choose 'Calculated number' from the bottom of the 'Type' dropdown.

Ardoq calculated number

Step 2: Select where the field should apply

Specify if the calculated number field should apply to all components in the workspace of only to a few of them.

Ardoq apply field

Step 3: Create the field

This will take you to a Gremlin Query editor.

Ardoq create query

Step 4: Edit the query 

  • Go to Preferences > Organization settings > Manage fields.

  • Locate the calculated number field you created in step 1.

  • Click on the ‘Edit calculation’ button to modify the calculation.

ardoq edit query

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.

Ardoq edit query

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 5: 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 night, and you can trigger it from the Workspace sidebar when the workspace is open.

Ardoq recalculated field values

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:

Ardoq manage fields
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
  )

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 my calculated query missing/deleted? 

If the field the calculated query is connected to is removed, the query will also be deleted.

Did this answer your question?