huawei-cloud-ges-graph

⚠️ 実行方法（必ずお読みください）：このスキルは、scripts/ 配下のローカル Python または Node.js スクリプトを使ってクエリを実行します。API を直接呼び出すことは禁止されています。

• クエリスクリプトはスキルディレクトリの scripts/ 配下にあります（例：scripts/ges_graph_skill.py）。
• すべてのスクリプトと環境チェック用スクリプトはスキルパッケージ内にあります。実行するには skill action=exec を使用してください。シェルから直接実行しないでください。
• 一時スクリプトファイルを作成せず、インライン実行（python -c または node -e）を優先してください。詳しくは、以下の「インライン実行（一時ファイルなし）」セクションを参照してください。
• すべてのパスは、SKILL.md があるディレクトリであるスキルディレクトリからの相対パスです。

GES グラフアクセスガイド

概要

Huawei Cloud Graph Engine Service（GES）永続版のアトミック機能を提供し、 グラフデータベース操作へのアクセス方法を案内します。 Cypher クエリ、GQL クエリ、スキーマ／ラベル管理、サマリー情報のクエリ、グラフデータの編集など、主要な機能を網羅しています。

ディレクトリ構成

ディレクトリの構成は次のとおりです（すべてのパスはスキルディレクトリからの相対パスです）。

1. scripts/ - Python および Node.js の実行スクリプトが含まれています
   • ges_graph_skill.py - GES のグラフ操作用 Python SDK
   • ges_graph_skill.js - GES のグラフ操作用 Node.js SDK
2. references/ - ドキュメントと設定例が含まれています
   • ges_env.csv.example - 環境設定テンプレート

前提条件

このスキルを使用する前に、以下の条件を満たしていることを確認してください。

1. ランタイム環境

Python または Node.js のランタイムをサポートしています。 Python 3.8 以降、または Node.js 14 以降が必要です。

2. グラフインスタンスの設定

このスキルでは、環境変数と設定ファイルの両方をサポートしています。環境変数は設定ファイルより優先されます。

環境変数とパラメーター

環境変数	説明	必須
GES_GRAPH_IP	GES サービスの IP	はい
GES_GRAPH_PORT	GES サービスのポート	はい
GES_PROJECT_ID	プロジェクト ID	はい
GES_GRAPH_NAME	グラフ名	はい
GES_IAM_URL	IAM サービスの URL	はい
GES_REGION	リージョン	はい
HUAWEI_CLOUD_AK	アクセスキー	はい*
HUAWEI_CLOUD_SK	シークレットキー	はい*
GES_USERNAME	ユーザー名	条件付き**
GES_PASSWORD	パスワード	条件付き**
GES_DOMAIN_NAME	ドメイン名	条件付き**
GES_TOKEN	トークン（最優先）	任意

• AK/SK 認証には AK/SK が必要です。 ** AKSK が利用できない場合は、ユーザー名／パスワードが条件付きで必要です。

設定ファイル（.env/ges_env.csv）

設定ファイルのパス：.env/ges_env.csv

設定項目	説明	必須	値の例
graph_ip	GES サービスの IP	はい	100.95.xxx.xxx
graph_port	GES サービスのポート	はい	80
project_id	プロジェクト ID	はい	your_project_id
graph_name	グラフ名	はい	your_graph_name
iam_url	IAM サービスの URL	はい	（下記のリージョン表を参照）
access_key	アクセスキー	はい*	your_access_key
secret_key	シークレットキー	はい*	your_secret_key
username	ユーザー名	条件付き**	your_username
password	パスワード	条件付き**	your_password
domain_name	ドメイン名	条件付き**	your_domain_name
region	リージョン	はい	cn-north-4

• AKSK 認証には access_key／secret_key が必要です。 ** AKSK が利用できない場合は、username／password／domain_name が条件付きで必要です。

リージョン別 IAM URL

リージョン	URL	プロトコル
cn-north-4	iam.cn-north-4.myhuaweicloud.com/v3/auth/tokens	HTTPS
ap-southeast-1	iam.ap-southeast-1.myhuaweicloud.com/v3/auth/tokens	HTTPS

以下の3つの方法がサポートされています（優先度の高い順）：

1. 環境変数 GES_TOKEN
2. AKSK 方式（HUAWEI_CLOUD_AK + HUAWEI_CLOUD_SK または access_key + secret_key）
3. パスワード方式（ユーザー名 + パスワード + domain_name）

⛔ 禁止操作（安全ガードレール）

このスキルでは、以下の操作を禁止しています：

禁止操作	説明	理由
❌ 機密認証情報の出力	AK/SK、パスワード、トークン、その他の機密情報の出力	機密情報が漏えいするリスク

以下の高リスク操作を実行するには、事前にエージェントによる明示的な確認が必要です：

高リスク操作	説明	確認プロンプト
⚠️ グラフデータの全消去	clear_graph() または同様の消去操作	"グラフ内のすべてのデータを消去してもよろしいですか？この操作は元に戻せません。"
⚠️ ノード／エッジの一括削除	すべてのノードまたはエッジを無条件で一括削除	"すべてのノード／エッジを一括削除してもよろしいですか？この操作は元に戻せません。"

ユーザーが上記の高リスク操作を要求した場合、明示的な確認を得る必要があります： "これは高リスク操作であり、明示的な確認が必要です。続行するには「confirm」と返信してください。"

Cypher と GQL クエリ言語

GES は2つのクエリ言語、Cypher（Neo4j 互換）と GQL（国際標準のグラフクエリ言語）をサポートしています。

Cypher の使用方法

Python：

# Execute a Cypher query
result = skill.execute_query("MATCH (n) RETURN n LIMIT 10")

# Create a node (_ID_ is used only during creation to set a custom ID)
result = skill.execute_query(
    "CREATE (n:Person {_ID_: 'p001', name: '张三'}) RETURN n"
)

# Match query
result = skill.execute_query(
    "MATCH (n:Person)-[:KNOWS]->(m) WHERE n.name = '张三' RETURN m"
)

# Update a node (match via id() function)
result = skill.execute_query(
    "MATCH (n) WHERE id(n) = 123 SET n.name = '李四' RETURN n"
)

# Delete a node
result = skill.execute_query(
    "MATCH (n) WHERE id(n) = 123 DETACH DELETE n"
)

# Aggregate query
result = skill.execute_query(
    "MATCH (n:Person) RETURN n.city, count(*) as cnt ORDER BY cnt DESC"
)

Node.js：

const { GESGraphSkill } = require('./ges_graph_skill.js');
const skill = new GESGraphSkill();

// Execute a Cypher query
const result = await skill.executeQuery("MATCH (n) RETURN n LIMIT 10");

// Create a node (_ID_ is used only during creation to set a custom ID)
const result = await skill.executeQuery(
    "CREATE (n:Person {_ID_: 'p001', name: '张三'}) RETURN n"
);

// Match query
const result = await skill.executeQuery(
    "MATCH (n:Person)-[:KNOWS]->(m) WHERE n.name = '张三' RETURN m"
);

// Update a node
const result = await skill.executeQuery(
    "MATCH (n) WHERE id(n) = 123 SET n.name = '李四' RETURN n"
);

// Delete a node
const result = await skill.executeQuery(
    "MATCH (n) WHERE id(n) = 123 DETACH DELETE n"
);

// Aggregate query
const result = await skill.executeQuery(
    "MATCH (n:Person) RETURN n.city, count(*) as cnt ORDER BY cnt DESC"
);

// Path query
const result = await skill.executeQuery(
    "MATCH p=(n:Person)-[*1..3]->(m) WHERE n.name = '张三' RETURN p"
);

インライン実行（一時ファイルなし）

スクリプトファイルを作成せずに、skill action=exec を使って Cypher クエリを直接実行できます。

注： skill action=exec で実行する場合、作業ディレクトリはプロジェクトのルートです。インストール済みのスキルは skills/ai/ges/ ではなく、.agents/skills/huawei-cloud-ges-graph にあります。

Python：

skill exec py -c "
import sys, os; cwd=os.getcwd()
skill_dir = os.path.join(cwd, '.agents', 'skills', 'huawei-cloud-ges-graph')
sys.path.insert(0, os.path.join(skill_dir, 'scripts'))
from ges_graph_skill import get_skill
import json
r = get_skill().execute_query('MATCH (n) RETURN n LIMIT 5')
print(json.dumps(r, ensure_ascii=False, indent=2))
"

Node.js：

skill exec node -e "
const path = require('path');
const cwd = process.cwd();
const scriptPath = path.join(cwd, '.agents', 'skills', 'huawei-cloud-ges-graph', 'scripts', 'ges_graph_skill.js');
const { GESGraphSkill } = require(scriptPath);
(async () => {
    const r = await new GESGraphSkill().executeQuery('MATCH (n) RETURN n LIMIT 5');
    console.log(JSON.stringify(r, null, 2));
})();
"

よく使われる Cypher 文

カテゴリー	文	説明
スキーマ	call db.schema()	グラフスキーマ情報を取得
インデックス	call db.indexes()	すべてのインデックスを表示
クエリの終了	call dbms.killQuery('queryId')	実行中のクエリを終了
実行中のクエリ	call dbms.listQueries()	現在のクエリを表示
システムパラメーター	call dbms.parameter('needNodeIndex', false)	インデックス制約を解除（大規模グラフのシナリオ）

GQL の使用方法（このスキルでサポート）

GQL は ISO/IEC 39075 で標準化されたグラフクエリ言語です。GES は action_id=execute-gql-query を使って GQL を呼び出します。

# GQL requires the underlying _request method
client = GESClient()
result = client._request('POST', '/action?action_id=execute-gql-query', json={
    "statements": [{
        "statement": "INSERT (n:Person{_ID_:'p001', firstName:'Eywa'}) RETURN n",
        "parameters": {},
        "resultDataContents": ["row"]
    }]
})

よく使われる GQL 文

カテゴリー	文	説明
挿入	INSERT (n:Person{_ID_:'p001', firstName:'Eywa'}) RETURN n	ノードを挿入
マッチ	MATCH (n:Person WHERE element_id(n)='p001') RETURN n	条件に一致するものを検索
更新	MATCH (n:Person WHERE element_id(n)='p001') SET n.lastName='Higgo' RETURN n	プロパティを更新
プロパティの削除	MATCH (n:Person WHERE element_id(n)='p001') REMOVE n.lastName RETURN n	プロパティを削除
ノードの削除	MATCH (n:Person WHERE element_id(n)='p001') DELETE n	ノードを削除
フィルター	MATCH (n:Person)-[:KNOWS]->(m) FILTER element_id(n)='7933' AND m.gender='male' RETURN m	結果をフィルタリング
FOR ループ	FOR a IN [1,2,3] RETURN a	ループ文
LET 変数	LET a = 1, b = 2 RETURN a, b	変数の定義
UNION	... UNION ALL ...	結果セットを統合

Cypher と GQL の主な違い

機能	Cypher	GQL
内部 ID	id(n)	element_id(n)
カスタム ID（挿入時のみ）	_ID_ プロパティ	_ID_ プロパティ
ノードのマッチング	MATCH (n)	MATCH (n WHERE ...)
SET 文	SET n.prop = value	SET n.prop = value
プロパティの削除	REMOVE n.prop	REMOVE n.prop
ループ	サポートされていません	FOR x IN [...]
変数の定義	サポートされていません	LET x = value

Cypher クエリ

# Execute a Cypher query
result = skill.execute_query("MATCH (n) RETURN n LIMIT 10")

# Execute a Cypher query with parameters
result = skill.execute_query(
    "MATCH (n) WHERE n.name = $name RETURN n",
    parameters={"name": "张三"}
)

頂点の操作

# Add a node
result = skill.client.add_node(
    node_id="mem_001",
    labels=["Memory", "conversation"],
    properties={"content": "User said Hello", "timestamp": 1234567890}
)

# Batch add nodes
result = skill.client.add_nodes_batch([
    {"id": "mem_001", "labels": ["Memory"], "properties": {"content": "test1"}},
    {"id": "mem_002", "labels": ["Memory"], "properties": {"content": "test2"}}
])

# Get a node
result = skill.client.get_node("mem_001")

# Update a node
result = skill.client.update_node("mem_001", {"content": "New content"})

# Delete a node
result = skill.client.delete_node("mem_001")

エッジの操作

# Add an edge
result = skill.client.add_edge(
    start_node_id="mem_001",
    end_node_id="mem_002",
    edge_type="RELATED_TO",
    properties={"weight": 0.8}
)

# Delete an edge
result = skill.client.delete_edge("mem_001", "mem_002", "RELATED_TO")

# Get edges of a node
result = skill.client.get_edges("mem_001", direction="both")

ラベルの操作

# Add a label to a node
result = skill.client.add_label_to_node("mem_001", "important")

# Query nodes by label
result = skill.client.get_nodes_by_label("Memory", limit=100)

グラフの管理

# Get schema information
result = skill.get_schema_info()

# Get graph statistics
result = skill.get_statistics()

# Clear all data in the graph (dangerous operation)
result = skill.clear_all_memories()

インポート／エクスポート

# Import graph data
job_id = skill.client.import_graph(
    schema_path="obs://bucket/schema.xml",
    vertex_path="obs://bucket/vertex",
    edge_path="obs://bucket/edge"
)

# Export graph data (access_key/secret_key are read from .env automatically)
job_id = skill.client.export_graph(
    export_path="obs://bucket/export",
    vertex_set_name="set_vertex",
    edge_set_name="set_edge"
)

GES 構文ガイド

ノード ID の扱い

GES では、文字列型のノード ID を扱うために、特殊な _ID_ プロパティを使用します。

• ノードの作成では、_ID_ プロパティを使用します。

  CREATE (n:Memory{_ID_: 'mem_001', content: 'test'})
  

• その他の操作では、id() 関数を使用します。

  MATCH (n) WHERE id(n) = 'mem_001' RETURN n
  MATCH (n)-[r]->(m) WHERE id(n) = 'mem_001' RETURN r
  

スキーマ要件

GES では、対応するノードを作成する前に、スキーマ（ラベルとプロパティ）を定義する必要があります。スキーマは、次の方法で定義できます。

1. GES 管理コンソールでラベルとプロパティを作成する
2. インポートインターフェースを使用して、スキーマを含むデータをインポートする

レスポンス形式

すべての Cypher インターフェースは、統一された JSON 形式を返します。

{
  "results": [
    {
      "columns": ["column1", "column2"],
      "data": [
        {"row": ["value1", "value2"], "meta": [null, null]}
      ]
    }
  ],
  "errors": []
}

エラー処理

from ges_graph_skill import get_skill

skill = get_skill()
try:
    result = skill.execute_query("MATCH (n) RETURN n")
except Exception as e:
    print(f"Error: {e}")

重要な注意事項

1. トークンの有効性：トークンの有効期間は 24 時間です。コードによって自動的に更新されます
2. スキーマの制約：ノードを作成する前に、ラベルとプロパティが定義されていることを確認してください
3. 危険な操作：clear_graph() はグラフ内のすべてのデータを削除します。慎重に使用してください
4. 非同期操作：大規模なデータのインポート／エクスポートには、非同期モードを推奨します

参考ドキュメント

• 設定ファイルの形式：references/ges_env.csv.example — 環境設定ファイルのテンプレートとフィールドの説明
• グラフデータベースの形式：https://support.huaweicloud.com/usermanual-ges/ges_01_0153.html — GES グラフデータ形式の詳細なドキュメント
• ビジネス API へのアクセス方法：https://support.huaweicloud.com/api-ges/ges_03_0112.html — GES ビジネス API のアクセスガイド