Azure Cosmos DB for Gremlin グラフのサポートと、TinkerPop 機能との互換性
適用対象: 
Gremlin
Azure Cosmos DB は、Gremlin と呼ばれる、Apache TinkerPop のグラフ トラバーサル言語をサポートしています。 Gremlin 言語を使用して、グラフ エンティティ (頂点と辺) の作成、エンティティ内のプロパティの変更、クエリとトラバーサルの実行、エンティティの削除を行うことができます。
Azure Cosmos DB Graph エンジンは Apache TinkerPop のトラバーサル ステップの仕様に厳密に従っていますが、実装には Azure Cosmos DB に固有の違いがあります。 この記事では、Gremlin の簡単なチュートリアルを提供し、Gremlin API でサポートされている Gremlin の機能を紹介します。
互換性のあるクライアント ライブラリ
次の表に、Azure Cosmos DB に対して使用できる一般的な Gremlin ドライバーを示します。
| ダウンロード | source | 作業の開始 | サポートまたは推奨されているコネクタのバージョン |
|---|---|---|---|
| .NET | GitHub の Gremlin.NET | .NET を使用してグラフを作成する | 3.4.13 |
| Java | Gremlin JavaDoc | Java を使用してグラフを作成する | 3.4.13 |
| Python | GitHub の Gremlin-Python | Python を使用してグラフを作成する | 3.4.13 |
| Gremlin コンソール | TinkerPop ドキュメント | Gremlin コンソールを使用してグラフを作成する | 3.4.13 |
| Node.js | GitHub の Gremlin-JavaScript | Node.js を使用してグラフを作成する | 3.4.13 |
| PHP | GitHub の Gremlin-PHP | PHP を使用してグラフを作成する | 3.1.0 |
| Go Lang | Go Lang | このライブラリは、外部の共同作成者によって作成されています。 Azure Cosmos DB チームは、このライブラリのサポートやメンテナンスを一切提供していません。 |
注意
バージョンが 3.5.*、3.6.* の Gremlin クライアント ドライバーには既知の互換性の問題があるため、上記の、サポートされている最新バージョンである 3.4.* ドライバーを使用することをお勧めします。 この表は、これらの新しいバージョンのドライバーについて、互換性の問題が対処されたときに更新されます。
サポートされているグラフ オブジェクト
TinkerPop は、さまざまなグラフ テクノロジに対応する標準です。 そのため、グラフ プロバイダーによって提供される機能を説明する標準的な用語があります。 Azure Cosmos DB は、複数のサーバーまたはクラスター間でパーティション分割できる、永続的でコンカレンシーの高い書き込み可能なグラフ データベースを提供します。
次の表に、Azure Cosmos DB で実装されている TinkerPop の機能を示します。
| カテゴリ | Azure Cosmos DB 実装 | Notes |
|---|---|---|
| グラフ機能 | 永続化と同時アクセスが提供されます。 トランザクションをサポートするように設計されています。 | コンピューターのメソッドは、Spark コネクタを介して実装できます。 |
| 変数機能 | ブール値、整数、Byte、Double、Float、Long、文字列をサポートしています。 | プリミティブ型をサポートしています。データ モデルを介して複雑な型と互換性があります。 |
| 頂点機能 | RemoveVertices、MetaProperties、AddVertices、MultiProperties、StringIds、UserSuppliedIds、AddProperty、RemoveProperty をサポートしています。 | 頂点の作成、変更、削除をサポートしています。 |
| 頂点プロパティ機能 | StringIds、UserSuppliedIds、AddProperty、RemoveProperty、BooleanValues、ByteValues、DoubleValues、FloatValues、IntegerValues、LongValues、StringValues | 頂点プロパティの作成、変更、削除をサポートしています。 |
| 辺機能 | AddEdges、RemoveEdges、StringIds、UserSuppliedIds、AddProperty、RemoveProperty | 辺の作成、変更、削除をサポートしています。 |
| 辺プロパティ機能 | Properties、BooleanValues、ByteValues、DoubleValues、FloatValues、IntegerValues、LongValues、StringValues | 辺プロパティの作成、変更、削除をサポートしています。 |
Gremlin のワイヤ形式
Azure Cosmos DB では、Gremlin の操作から結果を返すときに JSON 形式を使用します。 Azure Cosmos DB では現在、JSON 形式がサポートされています。 たとえば、次のスニペットは、Azure Cosmos DB から "クライアントに返される" JSON による頂点の表現を示しています。
{
"id": "a7111ba7-0ea1-43c9-b6b2-efc5e3aea4c0",
"label": "person",
"type": "vertex",
"outE": {
"knows": [
{
"id": "3ee53a60-c561-4c5e-9a9f-9c7924bc9aef",
"inV": "04779300-1c8e-489d-9493-50fd1325a658"
},
{
"id": "21984248-ee9e-43a8-a7f6-30642bc14609",
"inV": "a8e3e741-2ef7-4c01-b7c8-199f8e43e3bc"
}
]
},
"properties": {
"firstName": [
{
"value": "Thomas"
}
],
"lastName": [
{
"value": "Andersen"
}
],
"age": [
{
"value": 45
}
]
}
}
JSON 形式で使用される頂点のプロパティを次に説明します。
| プロパティ | 説明 |
|---|---|
id |
頂点の ID。 一意である必要があります (該当する場合は、_partition の値との組み合わせにおいて一意である必要があります)。 値が指定されていない場合は、GUID が自動的に提供されます |
label |
頂点のラベル。 このプロパティは、エンティティの種類を示すために使用します。 |
type |
頂点とグラフ以外のドキュメントを区別するために使用します。 |
properties |
頂点に関連付けられているユーザー定義プロパティのバッグ。 各プロパティには複数の値を指定できます。 |
_partition |
頂点のパーティション キー。 グラフのパーティション分割に使用されます。 |
outE |
このプロパティには、頂点からの外向きの辺のリストが含まれます。 頂点と共に隣接情報を格納することで、トラバーサルの高速実行が可能になります。 辺はラベルに基づいてグループ化されます。 |
各プロパティでは、配列内に複数の値を格納できます。
| プロパティ | 説明 |
|---|---|
value |
プロパティの値。 |
辺には、グラフの他の部分へのナビゲーションに役立つ次の情報が含まれています。
| プロパティ | 説明 |
|---|---|
id |
辺の ID。 一意である必要があります (該当する場合は、_partition の値との組み合わせにおいて一意である必要があります) |
label |
辺のラベル。 このプロパティは省略可能です。関係の種類を示すために使用します。 |
inV |
このプロパティには、辺の頂点一覧が含まれています。 辺と共に隣接情報を格納することで、トラバーサルの高速実行が可能になります。 頂点はラベルに基づいてグループ化されます。 |
properties |
辺に関連付けられているユーザー定義プロパティのバッグ。 |
Gremlin のステップ
次に、Azure Cosmos DB でサポートされている Gremlin のステップを見てみましょう。 Gremlin の完全なリファレンスについては、TinkerPop リファレンスをご覧ください。
| ステップ | 説明 | TinkerPop 3.2 ドキュメント |
|---|---|---|
addE |
2 つの頂点の間に辺を追加します。 | addE ステップ |
addV |
グラフに頂点を追加します。 | addV ステップ |
and |
すべてのトラバーサルが値を返すようにします。 | and ステップ |
as |
ステップの出力に変数を割り当てるステップ モジュレーター。 | as ステップ |
by |
group および order と共に使用するステップ モジュレーター。 |
by ステップ |
coalesce |
結果を返す最初のトラバーサルを返します。 | coalesce ステップ |
constant |
定数値を返します。 coalesce と共に使用します。 |
constant ステップ |
count |
トラバーサルからカウントを返します。 | count ステップ |
dedup |
重複を削除して値を返します。 | dedup ステップ |
drop |
値 (頂点/辺) を破棄します。 | drop ステップ |
executionProfile |
実行された Gremlin ステップによって生成されたすべての操作の記述を作成します | executionProfile ステップ |
fold |
結果の集計を計算するバリアとして機能します。 | fold ステップ |
group |
指定されたラベルに基づいて値をグループ化します。 | group ステップ |
has |
プロパティ、頂点、辺をフィルター処理するときに使用します。 hasLabel、hasId、hasNot、has の各バリアントをサポートします。 |
has ステップ |
inject |
値をストリームに挿入します。 | inject ステップ |
is |
ブール式を使用してフィルターを実行するときに使用します。 | is ステップ |
limit |
トラバーサルで項目の数を制限するときに使用します。 | limit ステップ |
local |
サブクエリと同様に、トラバーサルのセクションをローカルでラップします。 | local ステップ |
not |
フィルターの否定を生成するときに使用します。 | not ステップ |
optional |
指定されたトラバーサルの結果が生成された場合は、その結果を返します。それ以外の場合は、呼び出し元の要素を返します。 | optional ステップ |
or |
少なくとも 1 つのトラバーサルで値が返されるようにします。 | or ステップ |
order |
指定された並べ替え順序で結果を返します。 | order ステップ |
path |
トラバーサルの完全なパスを返します。 | path ステップ |
project |
プロパティをマップとして投影します。 | project ステップ |
properties |
指定されたラベルのプロパティを返します。 | properties ステップ |
range |
値の指定された範囲にフィルターを適用します。 | range ステップ |
repeat |
ステップを指定された回数繰り返します。 ループに使用します。 | repeat ステップ |
sample |
トラバーサルの結果をサンプリングするときに使用します。 | sample ステップ |
select |
トラバーサルの結果を予想するときに使用します。 | select ステップ |
store |
トラバーサルの非ブロッキング集計に使用します。 | store ステップ |
TextP.startingWith(string) |
文字列フィルター処理関数。 この関数は、指定された文字列で始まるプロパティを照合するための has() ステップの述語として使用されます。 |
TextP 述語 |
TextP.endingWith(string) |
文字列フィルター処理関数。 この関数は、指定された文字列で終わるプロパティを照合するための has() ステップの述語として使用されます。 |
TextP 述語 |
TextP.containing(string) |
文字列フィルター処理関数。 この関数は、指定された文字列の内容を含むプロパティを照合するための has() ステップの述語として使用されます。 |
TextP 述語 |
TextP.notStartingWith(string) |
文字列フィルター処理関数。 この関数は、指定された文字列で始まらないプロパティを照合するための has() ステップの述語として使用されます。 |
TextP 述語 |
TextP.notEndingWith(string) |
文字列フィルター処理関数。 この関数は、指定された文字列で終わらないプロパティを照合するための has() ステップの述語として使用されます。 |
TextP 述語 |
TextP.notContaining(string) |
文字列フィルター処理関数。 この関数は、指定された文字列を含んでいないプロパティを照合するための has() ステップの述語として使用されます。 |
TextP 述語 |
tree |
頂点からのパスを集計してツリーを形成します。 | tree ステップ |
unfold |
反復子をステップとしてアンロールします。 | unfold ステップ |
union |
複数のトラバーサルの結果をマージします。 | union ステップ |
V |
頂点および辺の間でのトラバーサルに必要なステップ (V、E、out、in、both、outE、inE、bothE、outV、inV、bothV、otherV) が含まれています。 |
vertex ステップ |
where |
トラバーサルの結果をフィルター処理するときに使用します。 eq、neq、lt、lte、gt、gte、between の各演算子をサポートします。 |
where ステップ |
Azure Cosmos DB によって提供された書き込みに最適化されたエンジンは、頂点および辺内のすべてのプロパティの自動インデックス作成を既定でサポートしています。 そのため、任意のプロパティでのフィルターを使用するクエリ、範囲クエリ、並べ替え、または集計は、インデックスに基づいて処理され、効率的に提供されます。 Azure Cosmos DB におけるインデックス作成のしくみの詳細については、スキーマに依存しないインデックス作成に関する論文をご覧ください。
動作の違い
- Azure Cosmos DB Graph エンジンでは "幅優先" トラバーサルが実行されますが、TinkerPop Gremlin では深さ優先になります。 この動作により、Azure Cosmos DB のように水平方向にスケーラブルなシステムでのパフォーマンスが向上します。
サポートされていない機能
Gremlin バイトコードは、プログラミング言語に依存しない、グラフ トラバーサルの仕様です。 Azure Cosmos DB Graph ではまだサポートされていません。
GremlinClient.SubmitAsync()を使用して、トラバーサルをテキスト文字列として渡してください。property(set, 'xyz', 1)set カーディナリティは現在サポートされていません。 代わりにproperty(list, 'xyz', 1)を使用してください 詳細については、TinkerPop での頂点プロパティに関する記事を参照してください。match()ステップは、現在利用できません。 このステップでは、宣言型のクエリ機能が提供されます。頂点または辺のプロパティとしてのオブジェクトはサポートされていません。 プロパティには、プリミティブ型または配列のみを指定できます。
配列プロパティによる並べ替え
order().by(<array property>)はサポートされていません。 プリミティブ型での並べ替えのみがサポートされています。非プリミティブ JSON 型はサポートされていません。
string型、number型、またはtrue/false型を使用してください。null値はサポートされていません。GraphSONv3 シリアライザーは現在サポートされていません。 接続構成で
GraphSONv2シリアライザー、リーダー、およびライター クラスを使用してください。 Azure Cosmos DB for Gremlin によって返される結果は、GraphSON 形式と同じ形式ではありません。ラムダ式と関数は現在サポートされていません。 これには、
.map{<expression>}、.by{<expression>}、および.filter{<expression>}関数が含まれます。 詳細について、および Gremlin の手順を使用してこれらを書き換える方法については、ラムダ式に関する注意事項に関する記事を参照してください。システムの分散型の性質により、トランザクションはサポートされていません。 Gremlin アカウントで "自分の書き込みを読み取る" ように適切な整合性モデルを構成し、オプティミスティック同時実行制御を使用して、競合する書き込みを解決してください。
既知の制限事項
- トラバーサル中の
.V()ステップによる Gremlin クエリのインデックス使用率:現時点では、トラバーサルの最初の.V()呼び出しのみによって、アタッチされているフィルターまたは述語を解決するために、インデックスが利用されます。 後続の呼び出しでは、インデックスが参照されないため、クエリの待機時間とコストが増加する可能性があります。
既定のインデックス作成を前提とすると、.V() ステップによって開始された通常の読み取り Gremlin クエリでは、.has() や .where() など、アタッチされたフィルター処理のステップの中でパラメーターが使用され、クエリのコストとパフォーマンスが最適化されます。 次に例を示します。
g.V().has('category', 'A')
ただし、2 つ以上の .V() ステップが Gremlin クエリ内に含まれている場合、そのクエリのデータの解決は最適でない可能性があります。 例として、次のクエリを取り上げます。
g.V().has('category', 'A').as('a').V().has('category', 'B').as('b').select('a', 'b')
このクエリでは、category というプロパティに基づいて、2 つの頂点のグループが返されます。 この場合、最初の呼び出しの g.V().has('category', 'A') のみによって、インデックスが使用され、プロパティの値に基づいて頂点が解決されます。
このクエリでの回避策は、.map() および union() などのサブトラバーサル ステップを使用することです。 これは、以下のように例示されます。
// Query workaround using .map()
g.V().has('category', 'A').as('a').map(__.V().has('category', 'B')).as('b').select('a','b')
// Query workaround using .union()
g.V().has('category', 'A').fold().union(unfold(), __.V().has('category', 'B'))
Gremlin の executionProfile() ステップを使用して、クエリのパフォーマンスを確認できます。