Documentation
ドキュメントの検索
karat

+

K

APIリファレンス ↗
オントロジーの構築ファンクションオントロジーの編集クエリ

注: 以下の翻訳の正確性は検証されていません。AIPを利用して英語版の原文から機械的に翻訳されたものです。

クエリ

クエリは関数のうち読み取り専用のもので、必要に応じて API ゲートウェイ経由で公開できます。オントロジーの変更や外部システムの変更などの副次的効果を持つことはできません。API ゲートウェイ経由でこうした追加の編集機能が必要な場合は、アクションを使用してください。

クエリデコレーター

クエリ関数を定義するには、次の構文を使用します。

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

@Query({ apiName: "myTypeScriptV1Function" })
Copied!
1
2
3
4
// 関数を含むファイルから、apiName パラメーターを持つ config オブジェクトをエクスポートします
export const config = {
    apiName: "myTypeScriptV2Function"
};
Copied!
1
2
3
from functions.api import function

@function(api_name="myPythonFunction")

Python および TypeScript v1 関数の場合、デコレーターは string 型のAPI名パラメーターを受け取ります。このパラメーターはAPI名の定義に必須です。TypeScript v1 を使用する場合、apiName パラメーターが定義されていなければ、クエリは既存の @Function デコレーターと同様に動作します。対応する Python の構文は api_name です。

例：API名付きクエリ

次の例は、API ゲートウェイ経由でクエリを公開する方法を示しています。

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 aircraftCount = await Objects.search().aircraft()
                 .filter(aircraft => aircraft.timeUntilNextFlight.range().gt(minimumTimeInMinutes))
                 .count();

        return aircraftCount!;
    }
}
Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import { Client } from "@osdk/client";
import { Double } from "@osdk/functions";
import { Aircraft } from "@ontology/sdk";

export const config = {
    apiName: "getReschedulableAircraftCount"
};

async function countAircraftTakingOffAfter(client: Client, minimumTimeInMinutes: Double): Promise<Double> {
    const { $count } = await client(Aircraft).where({
        timeUntilNextFlight: {
            $gt: minimumTimeInMinutes
        }
    }).aggregate({ $select: { $count: "unordered" } })

    return $count;
}

export default countAircraftTakingOffAfter;
Copied!
1
2
3
4
5
6
7
8
9
10
11
12
from functions.api import Double, function
from ontology_sdk import FoundryClient
from ontology_sdk.ontology.objects import Aircraft

@function(api_name="getReschedulableAircraftCount")
def count_aircraft_taking_off_after(minimum_time_in_minutes: Double) -> Double:
    client = FoundryClient()
    aircraft_count = client.ontology.objects.Aircraft.where(
        Aircraft.object_type.time_until_next_flight > minimum_time_in_minutes
    ).count().compute()

    return aircraft_count

API名の検証

クエリの apiName は、次の要件を満たす文字列である必要があります。

  • lowerCamelCase であること。
  • 100文字未満であること。
  • 先頭に数字を含まないこと。
  • リポジトリにインポートされたすべてのオントロジーにわたって一意であること。
    • apiName が一意でない場合、タグ付けプロセスに失敗するため、名前を変更する必要があります。

また、API名付きクエリを含むリポジトリは、1つ以上のオントロジーからエンティティをインポートする必要があります。

API名付きクエリのバージョンを管理し、更新する

API名付きクエリでは、公開済みクエリのタグ付けされた最新バージョンが常に使用され、ほかの Foundry 関数と同じセマンティックバージョニングの方式には従いません。

API名とクエリの関連付けを解除し、API ゲートウェイでそのクエリを使用できなくするには、クエリデコレーターからAPI名を削除し、リポジトリから新しいタグをリリースする必要があります。

デコレーター内のAPI名を変更して新しいタグを公開すると、利用側で動作しなくなります。クエリは、公開済みの最新バージョンのみがサポートされます。

利用側が破壊的変更の影響を受けずに都合のよいタイミングでアップグレードできるように、同じAPI名の複数のバージョンをサポートできます。そのためには、リポジトリ内でクエリコードのコピーを作成し、getReschedulableAircraftCountV2 などの異なるAPI名を付ける必要があります。

クエリを検索して表示する

ほかの関数と同様に、Ontology Managerでクエリを検索して管理できます。クエリ名またはAPI名で検索できます。上記の例では、API名での検索には getReschedulableAircraftCount を、クエリ名での検索には countAircraftTakingOffAfter を使用します。

Ontology Manager でクエリを検索する

TypeScript v1 関数を使用する場合、クエリを有効にするために、リポジトリ内の functions.json ファイルを更新して enableQueries プロパティを true に設定する必要がある場合があります。 

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

クエリ関数を呼び出す

TypeScript または Python のクエリ関数を公開した後、その関数を利用するコードリポジトリに移動し、リソースのインポートサイドバーを使用してインポートします。

利用側のリポジトリから関数を呼び出せるようになります。例を示します。

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);
    }
}
Copied!
1
2
3
4
5
6
7
8
9
import { Client } from "@osdk/client";
import { Double } from "@osdk/functions";
import { getReschedulableAircraftCount } from "@ontology/sdk";

async function callQueryFunction(client: Client): Promise<Double> {
    return client(getReschedulableAircraftCount).executeFunction({ timeUntilNextFlight: 10 });
}

export default callQueryFunction;
Copied!
1
2
3
4
5
6
7
8
from functions.api import Double, function
from ontology_sdk import FoundryClient

@function
def call_query_function() -> Double:
    return FoundryClient().ontology.queries.get_reschedulable_aircraft_count(
        time_until_next_flight=Double(10)
    )

TypeScript v1 関数では、公開済み関数から呼び出すクエリ関数と言語モデルのメソッドを Foundry が把握している必要があります。呼び出されるクエリの検出を試みる静的解析が自動的に提供されます。ただし、この静的解析では一部の呼び出しが検出されないことがあり、その結果、@Uses デコレーターの追加を指示する実行時エラーが発生する場合があります。このデコレーターは、自動検出されたクエリの使用情報を補完します。言語モデルのメソッドも同じ queries 配列に列挙します。

次の例は、@Uses デコレーターの使用方法を示しています。

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);
    }
}