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

To use the Query decorator, import it from the @foundry/functions-api package.

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

The decorator also accepts an optional parameter apiName of type string which you can use to define an API name.

Example: Simple query

This example of a simple query returns the count of aircrafts departing after a certain time. No API names are defined here. The simple query behaves similarly to Functions tagged with the existing @Function decorator.

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()
    public async countAircraftTakingOffAfter(minimumTimeInMinutes: Double): Promise<Double> {
        const aircaftCount = await Objects.search().aircraft()
                 .filter(aircraft => aircraft.timeUntilNextFlight.range().gt(minimumTimeInMinutes))
                 .count();

        return aircaftCount!;
    }
}

Example: API-named query

To make a query accessible via Foundry's API, we provide an optional parameter called apiName in the Query decorator. The example below demonstrates how to expose the previous 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 the Ontology Manager. You can search over the query name or the API name.

In the example below, the queries are getReschedulableAircraftCount for the API name and countAircraftTakingOffAfter for the query name, respectively.

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

Call queries in other Function repositories

You can import queries (including query functions published by AIP Logic) from the Resource imports tab found in the left sidebar in a Function code repository.

The imported query function can then be imported and called in the code like any other function.

## Example: Query function exposed by AIP Logic
# The example query function below is exposed by AIP Logic and has the API defined as "generateAText":
import { Objects, Queries } from "@foundry/ontology-api"; 

export class MyFunctions {

    @Function()
    public async myFunction(subject: string): Promise<string> {
        // Note: The below statement is equivalent to `Queries.generateAText({ subject: subject });`
        return Queries.generateAText({ subject });
    }
    
}