Query Language

Introduction

The DataLinks Query Language is a powerful domain-specific language designed to query and manipulate datasets within the DataLinks ecosystem. It provides a flexible and intuitive way to access data, apply filters, establish relationships between datasets, and sort results. This language is particularly useful for:

Retrieving data from specific datasets
Filtering data based on various conditions
Discovering relationships between different datasets
Traversing complex data structures
Sorting and limiting result sets
Counting, summing, averaging and grouping records

Basic Syntax

The query language follows a fluent interface pattern, where methods are chained together to build complex queries. The basic structure of a query is:

Ontology("<dataset>").<operation1>().<operation2>()...

OntologyObject("<dataset>").<operation1>().<operation2>()...

Both Ontology and OntologyObject are valid entry points for creating a query.

Querying Datasets

Basic Dataset Query

To query a dataset, specify its name:

Ontology("Movies")

Dataset names are case-insensitive, so Ontology("movies") and Ontology("Movies") refer to the same dataset.

Namespaced Datasets

Datasets can be organized in namespaces. To query a namespaced dataset, use the format:

Ontology("Namespace/Dataset")

For example:

Ontology("Companies/Orange")

If a dataset name is ambiguous (exists in multiple namespaces), you must specify the namespace to avoid errors.

Filtering Data

Basic Filtering

To filter data, use the filter() method with a comparison expression:

Ontology("Movies").filter(year == 2012)

Ontology("Movies").filter().column("year == 2012")

Comparison Operators

The query language supports the following comparison operators:

== (equal to)
!= (not equal to)
< (less than)
<= (less than or equal to)
> (greater than)
>= (greater than or equal to)

Examples:

Ontology("Movies").filter(year < 2000)
Ontology("Movies").filter(budget >= 10000000)
Ontology("Movies").filter(name != "Titanic")

Logical Operators

Combine multiple conditions using logical operators:

&& (AND)
|| (OR)

Examples:

Ontology("Movies").filter(year == 2005 && director == "Christopher Nolan")
Ontology("Movies").filter(year == 2005 || year == 2006)

Nested Conditions

Use parentheses to create complex nested conditions:

Ontology("Movies").filter(director == "Mark Osborne" && (year == 2005 || year == 2006))

Filter Expression Syntax

The query language provides flexible syntax for filter expressions:

Quoting Field Names: Field names can be unquoted, single-quoted, or double-quoted:

name == "value"
"name" == "value"
'name' == "value"

Quoting Values: String values can be unquoted (for simple strings) or quoted:

title == dog
title == "dog"
title == 'dog'

Multi-word Values: Multi-word string values must be quoted:

title == "The Matrix"

Note: Unquoted multi-word values (e.g., title == The Matrix) are not supported.

Linking Datasets

To find related datasets, use the searchAround() and find() methods:

Ontology("Movies").searchAround().find("Actor")

This searches for actors related to movies based on defined links between the datasets.

Specifying Search Depth

You can specify the depth of the search (how many hops to traverse):

Ontology("Movies").searchAround(2).find("Actor")

A depth of 2 means it will look for relationships that are two links away.

Following Specific Links

To follow specific columns when linking datasets:

Ontology("Movies").searchAround().find("Actor").follow("director")

This specifies that the link between Movies and Actor should be through the “director” column. You can specify multiple columns to follow:

Ontology("Movies").searchAround().find("Actor").follow("director", "producer")

Sorting and Limiting Results

Sorting Results

Sort results in ascending or descending order:

Ontology("Movies").sortAscending("year")
Ontology("Movies").sortDescending("budget")

Alternative syntax:

Ontology("Movies").sort("year", "ASC")
Ontology("Movies").sort("budget", "DESC")

Multiple Sort Criteria

Sort by multiple fields:

Ontology("Actor").sortDescending("nationality").sortAscending("age")

This sorts actors first by nationality in descending order, then by age in ascending order.

Limiting Results

Limit the number of results returned:

Ontology("Movies").limit(5)

You can also limit results at different stages of a complex query:

Ontology("Movies").limit(10).searchAround().find("Actor").limit(5)

This limits the movies to 10 and the related actors to 5.

Aggregations

Most aggregations replace the matched records with a computed result; countLinked() and sumLinked() instead keep every record and enrich it. Place the aggregation after find() when the query traverses links, or directly after Ontology() / filter() otherwise; after it, only filter(), sortAscending() / sortDescending() and limit() may follow (plus maxDepth() for the linked aggregations). groupBy() is always paired with one count(), sum() or avg(), and that pair counts as a single aggregation. Only one aggregation is supported per query — do not combine count(), sum(), avg(), groupBy(…).<reducer>(), countLinked() or sumLinked() with each other.

Operation	Returns
`count()`	One total: the number of matched records
`sum("col")`	One total: the sum of `col` across matched records
`avg("col")`	One value: the average of `col` across matched records
`groupBy("g").count()`	One row per distinct value of `g`, with `count.g`
`groupBy("g").sum("v")`	One row per distinct value of `g`, with `sum.v`
`groupBy("g").avg("v")`	One row per distinct value of `g`, with `avg.v`
`countLinked("Target")`	Each matched record, enriched with `_link_count`
`sumLinked("Target", "col")`	Each matched record, enriched with `sum.col`

Counting Records

count() returns a single number: how many records matched.

Ontology("Movies").count()
Ontology("Movies").filter(year < 2000).count()
Ontology("Movies").filter(director == "Mark Osborne").searchAround().find("Actor").count()

Aggregations placed directly on the root dataset are exact. After a searchAround().find() they run over the traversed records, which are capped at 10,000 — use countLinked() / sumLinked() when you need exact per-record totals over links.

Sum and Average

sum() and avg() compute a single total or average over a numeric column. The column argument is mandatory.

Ontology("Movies").sum("budget")
Ontology("Movies").filter(year == 2012).sum("budget")
Ontology("Movies").avg("budget")
Ontology("Movies").filter(director == "Christopher Nolan").avg("budget")

sum() and avg() only work on numeric columns.

Grouping

groupBy() groups the matched records by the distinct values of one or more columns and returns one synthetic row per group. It must be followed by count(), sum() or avg():

Ontology("Movies").groupBy("director").count()
Ontology("Movies").groupBy("director").sum("budget")
Ontology("Movies").groupBy("director").avg("budget")

Each returned row holds the group value(s) plus the computed metric, named after the operation and column:

groupBy("director").count() → director, count.director
groupBy("director").sum("budget") → director, sum.budget
groupBy("director").avg("budget") → director, avg.budget

Within groupBy(), sum() and avg() accept several value columns at once, producing one metric per column:

Ontology("Movies").groupBy("director").sum("budget", "revenue")

Group by several columns to get one row per distinct combination of values:

Ontology("Movies").groupBy("director", "year").sum("budget")
Ontology("Movies").groupBy("director", "year").count()

The count metric is then named after all the group columns in order:

groupBy("director", "year").sum("budget") → director, year, sum.budget
groupBy("director", "year").count() → director, year, count.director.year

The query language has no distinct() operation, but groupBy("column").count() returns one row per distinct value, so the number of rows returned is the number of distinct values. At most 10,000 groups are returned (the largest by record count unless sorted), and grouping a column with more than 100,000 distinct values is rejected:

Ontology("Movies").groupBy("director").count()

Filtering Groups

A filter() placed before the aggregation narrows the records that get aggregated. A filter() placed after a groupBy() aggregation applies to the groups it produced, comparing against the emitted metric — the equivalent of SQL’s HAVING. Both can appear in the same query:

Ontology("Movies").groupBy("director").count().filter(count.director > 2)
Ontology("Movies").groupBy("director").sum("budget").filter(sum.budget > 100000000)
Ontology("Movies").filter(year == 2024).groupBy("director").sum("budget").filter(sum.budget > 1000000)

After a groupBy() aggregation only the group column(s) and the metric exist on the rows. A filter that names any other column is rejected.

Sorting and Limiting Groups

Sort grouped results by their metric to get the top or bottom N groups:

Ontology("Movies").groupBy("director").sum("budget").sortDescending("sum.budget").limit(5)
Ontology("Movies").groupBy("director").count().sortDescending("count.director").limit(10)

Always pair limit() with a sort on the metric. Without a sort, groups come back ordered by record count, so an unsorted limit() returns the largest groups rather than the highest totals.Sorting on the bare value column (e.g. sortDescending("budget") instead of sortDescending("sum.budget")) is rejected, because that column no longer exists on the grouped rows.

Counting and Summing Linked Records

countLinked("X") / sumLinked("X", …) keep the matched records and add an aggregate over the linked records in X to each one. By default only direct (one-hop) links count:

Ontology("Actor").countLinked("Movies")

Returns every actor, each with _link_count: the number of movies they appear in.

Ontology("Actor").sumLinked("Movies", "boxOffice").sortDescending("sum.boxOffice").limit(10)

Returns the 10 actors whose movies earned the most, each with sum.boxOffice. sumLinked() accepts several numeric columns at once; each adds its own sum.<column> field:

Ontology("Actor").sumLinked("Movies", "budget", "boxOffice")

Returns every actor, each with sum.budget and sum.boxOffice. If X is further away, add maxDepth(n). The in-between datasets are found for you, and the results stay on your original records:

Ontology("Actor").sumLinked("Screenings", "ticketsSold").maxDepth(2)

Returns every actor, each with sum.ticketsSold: the tickets sold across all screenings of all their movies (Actor → Movies → Screenings). Each screening counts once per actor, however many paths reach it. To get the aggregate per record of an in-between dataset instead, traverse to it first and aggregate from there. The results then belong to that dataset, not to the one you started from:

Ontology("Actor").searchAround().find("Movies").sumLinked("Screenings", "ticketsSold")

Returns movies, not actors, each with sum.ticketsSold for that movie’s own screenings. A filter() placed after countLinked() / sumLinked() applies to the linked dataset’s columns and restricts which linked records are counted or summed:

Ontology("Movies").countLinked("Actor").filter(age < 40)

Unlike groupBy() metrics, the _link_count and sum.<column> fields produced by countLinked() / sumLinked() cannot be used in a filter(). Apply any threshold on the returned rows instead.

Natural Language Query Generation

The system can generate queries from natural language questions. For example: Natural language: “What is the age of the director of Braveheart?” Generated query:

OntologyObject("Movies").filter(name == "Braveheart").searchAround().find("Actor")

Examples

Basic Query Examples

Find all movies:

Ontology("Movies")

Find a specific movie:

Ontology("Movies").filter(name == "Argo")

Find movies released before 2000:

Ontology("Movies").filter(year < 2000)

Relationship Query Examples

Find actors who directed movies:

Ontology("Movies").searchAround().find("Actor")

Find movies directed by actors under 60:

Ontology("Actor").filter(age < 60).searchAround().find("Movies")

Find actors who directed movies, then find other actors who worked with them:

Ontology("Actor").filter(age < 60).searchAround().find("Movies").searchAround().find("Actor")

Sorting and Limiting Examples

Find the 3 oldest movies:

Ontology("Movies").sortAscending("year").limit(3)

Find the 5 highest budget movies:

Ontology("Movies").sortDescending("budget").limit(5)

Aggregation Examples

Count movies released before 2000:

Ontology("Movies").filter(year < 2000).count()

Total budget per director, top 5:

Ontology("Movies").groupBy("director").sum("budget").sortDescending("sum.budget").limit(5)

Directors with more than two movies:

Ontology("Movies").groupBy("director").count().filter(count.director > 2)

Movies ranked by number of linked actors:

Ontology("Movies").countLinked("Actor").sortDescending("_link_count").limit(10)

Error Handling

If a query returns unexpected results:

Check field names and table relationships for correctness.
Ensure the depth in searchAround is sufficient for your query.
Debug by breaking the query into smaller parts and testing them individually.

Get Started

How-To Guides

Understanding the UI

Reference

Concepts

Introduction

Basic Syntax

Querying Datasets

Basic Dataset Query

Namespaced Datasets

Filtering Data

Basic Filtering

Comparison Operators

Logical Operators

Nested Conditions

Filter Expression Syntax

Linking Datasets

Specifying Search Depth

Following Specific Links

Sorting and Limiting Results

Sorting Results

Multiple Sort Criteria

Limiting Results

Aggregations

Counting Records

Sum and Average

Grouping

Filtering Groups

Sorting and Limiting Groups

Counting and Summing Linked Records

Natural Language Query Generation

Examples

Basic Query Examples

Relationship Query Examples

Sorting and Limiting Examples

Aggregation Examples

Error Handling

​Introduction

​Basic Syntax

​Querying Datasets

​Basic Dataset Query

​Namespaced Datasets

​Filtering Data

​Basic Filtering

​Comparison Operators

​Logical Operators

​Nested Conditions

​Filter Expression Syntax

​Linking Datasets

​Searching Related Datasets

​Specifying Search Depth

​Following Specific Links

​Sorting and Limiting Results

​Sorting Results

​Multiple Sort Criteria

​Limiting Results

​Aggregations

​Counting Records

​Sum and Average

​Grouping

​Filtering Groups

​Sorting and Limiting Groups

​Counting and Summing Linked Records

​Natural Language Query Generation

​Examples

​Basic Query Examples

​Relationship Query Examples

​Sorting and Limiting Examples

​Aggregation Examples

​Error Handling

Introduction

Basic Syntax

Querying Datasets

Basic Dataset Query

Namespaced Datasets

Filtering Data

Basic Filtering

Comparison Operators

Logical Operators

Nested Conditions

Filter Expression Syntax

Linking Datasets

Searching Related Datasets

Specifying Search Depth

Following Specific Links

Sorting and Limiting Results

Sorting Results

Multiple Sort Criteria

Limiting Results

Aggregations

Counting Records

Sum and Average

Grouping

Filtering Groups

Sorting and Limiting Groups

Counting and Summing Linked Records

Natural Language Query Generation

Examples

Basic Query Examples

Relationship Query Examples

Sorting and Limiting Examples

Aggregation Examples

Error Handling