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.
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
.
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!; } }
The apiName
of a query must be a string that meets the following requirements:
lowerCamelCase
.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.
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.
Changing the API name in the decorator and publishing a new tag will break the consumer. Only the latest published version of the query is supported.
To allow consumers to upgrade at their convenience without breaking changes, you can support multiple versions of the same API name. To do this, you must make a copy of the query code in your repository and give it a different API name, for example getReschedulableAircraftCountV2
.
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.
When using TypeScript v1 functions, you may need to update the functions.json
file in your repository to enable queries by setting the enableQueries
property to true:
Copied!1 2 3
{ "enableQueries": true }
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); } }