Queries

Queries are the read-only subsets of functions that may be optionally exposed through the API gateway. They cannot have any side effects, such as modifying the Ontology or altering external systems. You should use an Action if you need those additional editing capabilities through the API gateway.

Query decorator

Use the following syntax to define a query function.

Copied!
1
2
3
import { Query } from "@foundry/functions-api";

@Query({ apiName: "myTypeScriptV1Function" })

For Python and TypeScript v1 functions, the decorator accepts an API name parameter of type string, which is required to define an API name. When using TypeScript v1, the query will behave similarly to the existing @Function decorator if the apiName parameter is not defined. Note that the corresponding Python syntax is api_name.

Example: API-named query

The example below demonstrates how to expose a query through the API gateway:

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
import { Query, Double } from "@foundry/functions-api";
import { Objects, Aircraft } from "@foundry/ontology-api";

export class PublishedQueries {
    @Query({ apiName: "getReschedulableAircraftCount" })
    public async countAircraftTakingOffAfter(minimumTimeInMinutes: Double): Promise<Double> {
        const aircaftCount = await Objects.search().aircraft()
                 .filter(aircraft => aircraft.timeUntilNextFlight.range().gt(minimumTimeInMinutes))
                 .count();

        return aircaftCount!;
    }
}

API name validations

The apiName of a query must be a string that meets the following requirements:

• Be in lowerCamelCase.
• Be under 100 characters.
• Not contain leading numbers.
• Be unique among all Ontologies imported into the repository.
  • The tagging process will fail if the apiName is not unique, requiring you to change the name.

Additionally, a repository containing API-named queries must import entities from at least one ontology.

Version and update API-named queries

API-named queries will always use the latest tagged version of the published query and do not follow the same semantic versioning paradigm as other Foundry functions.

To disassociate the API name from the query and break it in the API gateway, you must remove the API name from the query decorator and release a new tag from the repository.

Search and view queries

As with other functions, you can search for and manage your queries in Ontology Manager. You can search for the query name or the API name. In the example above, the queries are getReschedulableAircraftCount for the API name and countAircraftTakingOffAfter for the query name, respectively.

Copied!
1
2
3
{
  "enableQueries": true
}

Call a query function

After publishing your TypeScript or Python query function, navigate to the code repository where you want to consume the function, and import it using the Resource imports sidebar.

Your function will be callable from the consuming repository. For example:

Copied!
1
2
3
4
5
6
7
8
import { Queries } from "@foundry/ontology-api";

export class MyFunctions {
    @Function()
    public callQueryFunction(): Promise<Double> {
        return Queries.getReschedulableAircraftCount(10);
    }
}

For TypeScript v1 functions, Foundry must know which query functions you call from a published function. We automatically provide static analysis to try and detect queries that are called. However, this static analysis may occasionally miss certain calls leading to a runtime error instructing you to add the @Uses decorator. This decorator serves to augment the automatically detected query usage.

The following example demonstrates the usage of the @Uses decorator:

Copied!
1
2
3
4
5
6
7
8
9
10
import { Uses } from "@foundry/functions-api";
import { Queries } from "@foundry/ontology-api";

export class MyFunctions {
    @Uses({ queries: [Queries.getReschedulableAircraftCount] })
    @Function()
    public callQueryFunction(): Promise<Double> {
        return Queries.getReschedulableAircraftCount(10);
    }
}