neo4j-snowflake-graph-analytics-skill

Snowflake Native App — Snowflake 内でグラフアルゴリズムを実行できます。データは Snowflake 内に保持したまま、グラフに投影し、SQL CALL でアルゴリズムを実行して、結果を Snowflake のテーブルに書き戻します。

ドキュメント： https://neo4j.com/docs/snowflake-graph-analytics/current/

---

使用する場面

• Snowflake でグラフアルゴリズム／GDS を実行する場合
• データがすでに Snowflake のテーブルにある場合
• オンデマンド／パイプラインのワークロード — 一時的なセッションを使用し、セッション分単位で課金される場合
• 分析中にライブデータベースから完全に分離する場合

使用しない場面

• GDS プラグインを組み込んだ Aura Pro → neo4j-gds-skill
• Aura Graph Analytics → neo4j-aura-graph-analytics-skill
• GDS プラグインを組み込んだセルフマネージド Neo4j → neo4j-gds-skill
• Cypher クエリを書く場合 → neo4j-cypher-skill

---

エンドツーエンドのフロー

この手順で実行してください。いきなり CALL を実行しないでください。多くの失敗は、データの準備手順を省略することで起こります。

1. ソースデータを確認します — テーブルの DDL を調べ、列と型を把握します。
2. 投影ビューを準備します — 必要なキー列を公開し、すべてのプロパティをサポートされる型にキャストしたノード／リレーションシップのビューを作成します（以下の厳密なルールを参照）。最も重要な手順です。
3. 投影 → 計算 → 書き込み — project、compute、write の設定を組み立て、単一の CALL でアルゴリズムを実行します。
4. 確認して名前を参照します — 数値の結果をソーステーブルに結合し、人が読めるラベルを取得します。

---

手順 1 — ソースデータを確認する

グラフを設計する前に、テーブル定義を確認します。

SELECT GET_DDL('TABLE', 'MY_DATABASE.MY_SCHEMA.MY_TABLE');
-- or inspect columns/types:
SELECT COLUMN_NAME, DATA_TYPE
FROM MY_DATABASE.INFORMATION_SCHEMA.COLUMNS
WHERE TABLE_SCHEMA = 'MY_SCHEMA' AND TABLE_NAME = 'MY_TABLE';

どのテーブルをノードにし、どのテーブルがノード間のリレーションシップ（エッジ）を表すかを判断します。

---

手順 2 — 投影ビューを準備する（重要な手順）

グラフエンジンでは、列名と型が厳密に指定されています。**Snowflake のビューはデフォルトでソース列の型を引き継ぐため、明示的な CAST を必ず追加してください。**プロパティ列には CAST を付けずに SELECT col だけを使用しないでください。

テーブルをノード／リレーションシップ形式に整形するビューを作成します。

CREATE OR REPLACE VIEW MY_DATABASE.MY_SCHEMA.MY_NODES_VW AS
SELECT ... FROM MY_DATABASE.MY_SCHEMA.MY_TABLE;

ノードビュー

• キー列： 主キーを NODEID として公開します。型は BIGINT または STRING である必要があります。必ず別名を付け、明示的にキャストしてください。 SOURCE_COL::BIGINT AS NODEID または SOURCE_COL::STRING AS NODEID。
• 許可されるノードプロパティの型（以下のみ）： BIGINT、DOUBLE、ARRAY、VECTOR(FLOAT, n)。それ以外は、いずれかの型にキャストするか、除外する必要があります。
• 複合キー： 各部分を '++' で連結します。
• 命名規則： <table>_NODES_VW。

ソース型からビュー型へのキャスト規則

テーブルの列を投影するときは、列名を変更しない限り元の列名を維持したまま、次の規則を適用します。

ソース型	処理
整数型数値（INT、INTEGER、BIGINT、SMALLINT、TINYINT、BYTEINT、NUMBER(p,0)）	CAST(col AS BIGINT) AS col
小数型数値（FLOAT、DOUBLE、REAL、DECIMAL(p,s>0)、NUMBER(p,s>0)）	CAST(col AS DOUBLE) AS col
数値の ARRAY	ARRAY のまま維持します（GraphSAGE を除く — 以下を参照）。リレーションシップビューでは使用できません。
VECTOR(FLOAT, n)	そのまま維持します。リレーションシップビューでは使用できません。
BOOLEAN	デフォルトでは除外します。明示的に選択した場合のみ：IFF(col, 1, 0)::BIGINT AS col
DATE、TIME、TIMESTAMP*	デフォルトでは除外します。明示的に選択した場合のみ：DATE_PART('EPOCH_SECOND', col)::BIGINT AS col（単位をユーザーに伝えてください）
VARCHAR、CHAR、TEXT、STRING	除外します — グラフプロパティにはできません。名前で結果を参照するには、キーを使って出力をソーステーブルに結合します（手順 4 を参照）。
VARIANT、OBJECT、GEOGRAPHY、GEOMETRY、BINARY	除外します — グラフプロパティとしてサポートされていません。

最低共通分母の方針： デフォルトでは、安全な列（数値 → BIGINT／DOUBLE、ARRAY、VECTOR）のみを含めます。ブール値と時刻関連の列を含めるには、明示的な選択が必要です。列を除外する場合は、どの列をなぜ除外したかを簡潔にユーザーに伝え、必要であれば追加を依頼できるようにします。

リレーションシップビュー

• キー列： SOURCENODEID と TARGETNODEID を公開し、NODEID と同じルールでキャストします （SOURCE_COL::BIGINT AS SOURCENODEID など）。すべての値が、ノードビュー内の既存の NODEID と一致している必要があります。
• 使用可能なリレーションシッププロパティの型（より限定的）： BIGINT、DOUBLE、INT のみです。ARRAY と VECTOR は使用できません。（ドキュメントではリレーションシッププロパティを FLOAT としていますが、エンジンはこれらの整数・小数への数値キャストを受け付け、重みとして扱います。数値のままにしてください。）
• 命名規則： <table>_RELATIONSHIPS_VW。

ノードビューとリレーションシップビューの例：

CREATE OR REPLACE VIEW MY_DATABASE.MY_SCHEMA.USER_NODES_VW AS
SELECT user_id::BIGINT AS NODEID,
       CAST(age AS BIGINT)        AS age,
       CAST(balance AS DOUBLE)    AS balance
FROM MY_DATABASE.MY_SCHEMA.USERS;

CREATE OR REPLACE VIEW MY_DATABASE.MY_SCHEMA.TRANSFERS_RELATIONSHIPS_VW AS
SELECT from_user::BIGINT AS SOURCENODEID,
       to_user::BIGINT   AS TARGETNODEID,
       CAST(amount AS DOUBLE) AS amount
FROM MY_DATABASE.MY_SCHEMA.TRANSFERS;

必須の論理列名は nodeId／sourceNodeId／targetNodeId です。Snowflake は引用符で囲まれていない識別子を大文字に変換するため、NODEID などでも一致します。重要なのは明示的にキャストすることです。

---

ステップ 3 — プロジェクト化 → 計算 → 書き込み

各実行は、最初の引数がコンピュートプール、2 番目の引数が 3 つのパートから成る JSON 設定の単一の CALL です。Snowflake SQL では JSON にシングルクォートを使うことに注意してください。

アプリ名： Neo4j_Graph_Analytics は、インストール時のデフォルト名にすぎません。別の名前でアプリをインストールした場合は、プロシージャ呼び出し（<APP>.graph.<algo>）、preview.*／admin.* の呼び出し、USE DATABASE <APP> 文、および以下の権限付与など、すべての箇所で名前を置き換えてください。SHOW APPLICATIONS; で確認できます。

USE ROLE MY_CONSUMER_ROLE;

CALL Neo4j_Graph_Analytics.graph.wcc('CPU_X64_XS', {
    'defaultTablePrefix': 'MY_DATABASE.MY_SCHEMA',
    'project': {
        'nodeTables': ['USER_NODES_VW'],
        'relationshipTables': {
            'TRANSFERS_RELATIONSHIPS_VW': {
                'sourceTable': 'USER_NODES_VW',
                'targetTable': 'USER_NODES_VW',
                'orientation': 'NATURAL'
            }
        }
    },
    'compute': { 'consecutiveIds': true },
    'write': [{
        'nodeLabel': 'USER_NODES_VW',
        'outputTable': 'result_wcc_user_communities'
    }]
});

SELECT * FROM MY_DATABASE.MY_SCHEMA.result_wcc_user_communities;

設定の各パート

• defaultTablePrefix — ビューと出力テーブルがあるデータベースとスキーマを設定します（DB.SCHEMA）。これにより、短い名前で参照できます。
• project — nodeTables（配列。各要素がラベルに対応）と relationshipTables（マップ。各キーがタイプに対応し、sourceTable／targetTable／orientation を指定）を設定します。
• compute — アルゴリズムのパラメーターを指定します。値が null になるパラメーターは省略してください。
• write — 書き込み先のリストです。nodeLabel（または sourceLabel／targetLabel）には、書き込み対象のノードのテーブル名／ビュー名を指定します。リレーションシップの結果には relationshipType を使います。

方向

relationshipTables 内で、リレーションシップテーブルごとに orientation を設定します。

• NATURAL（デフォルト）— 有向。ソースからターゲットへ（テーブルに格納された方向）。
• UNDIRECTED — 双方向として扱います（各リレーションシップが両方向に含まれます）。
• REVERSE — 方向を反転します。ターゲットからソースへ。

アルゴリズムに応じて選択してください。

• UNDIRECTED — エッジを対称的に扱うコミュニティ検出：WCC、Louvain、Leiden、Label Propagation。Triangle Count には UNDIRECTED が必要です。
• NATURAL — 有向フローとランキング：PageRank、Article Rank、Dijkstra およびその他の経路探索アルゴリズム、Max Flow。Node Similarity では、NATURAL でプロジェクト化した二部グラフ（2 つの互いに素なノード集合）が想定されます。もう一方のノード集合を比較するには REVERSE を使います。
• KNN はリレーションシップを一切参照しません — 類似度はノードプロパティに基づくため、方向は影響しません（K-Means も同様にノードプロパティのみを使用します）。

コンピュートプール（最初の CALL 引数）

プール	用途
CPU_X64_XS	デフォルト — 開発／小規模グラフ
CPU_X64_S/M/L	段階的に大規模
HIGHMEM_X64_S/M/L	大規模グラフ、CPU 使用量が少ない場合
GPU_NV_XS、GPU_NV_S、GPU_GCP_NV_L4_1_24G	GraphSAGE／GPU 処理（利用可否はリージョンによって異なります）

ユーザーから別の指定がある場合、または GraphSAGE に GPU プールが適切な場合を除き、CPU_X64_XS を優先してください。ジョブの見積もりを参照してください。

結果テーブルの命名

出力テーブルには result_<algotag>_<short_description> という名前を付けてください。アンダースコアのみを使用し、スペースや特殊文字は使わないでください（例：result_louvain_customer_segments）。複数のノードラベルを書き込む場合は、ラベルごとに異なるテーブルを使用してください。

ステップ 4 — 名前の確認と参照

アルゴリズムが出力する内容は種類によって異なります。アルゴリズムの write 設定を確認してください。

• ノードプロパティの結果（中心性、コミュニティ検出、k-means、埋め込み、FastPath） — NODEID をキーとするテーブルです。
• リレーションシップの結果（Node Similarity、KNN、Dijkstra などの経路探索、Max Flow） — SOURCENODEID / TARGETNODEID をキーとするテーブルです。BFS やその他の異種書き込みでは、SOURCELABEL / TARGETLABEL も追加され、ノード ID は文字列として格納されます。
• モデル（GraphSAGE のトレーニング） — 出力テーブルはなく、モデルカタログに書き込まれます。後でモデルを予測に使用すると、ノードプロパティのテーブルが生成されます。

VARCHAR ラベルはプロジェクション時に削除されるため、読み取り可能な名前を取得するには、キー列を使って結果を ソーステーブル に結合します。ノードプロパティの結果では、NODEID で結合します。

SELECT u.name, u.country, r.score
FROM MY_DATABASE.MY_SCHEMA.result_page_rank_influence r
JOIN MY_DATABASE.MY_SCHEMA.USERS u
  ON r.NODEID = u.user_id
ORDER BY r.score DESC
LIMIT 10;

リレーションシップの結果では、ソーステーブルを 2 回結合します。一度は SOURCENODEID に、もう一度は TARGETNODEID に結合します。

---

利用可能なアルゴリズム

プロシージャ = Neo4j_Graph_Analytics.graph.<name>。以下の名前が正確な名前です。

アルゴリズムの計算／書き込みパラメーターの詳細なリファレンスについては、references/algorithms.md を参照してください。

コミュニティ検出

アルゴリズム	プロシージャ	使用例
弱連結成分	wcc	分断されたサブグラフを見つける
Louvain	louvain	コミュニティ検出（モジュラリティ）
Leiden	leiden	Louvain より安定したコミュニティ検出
ラベル伝播	label_propagation	ラベルの伝播による高速なコミュニティ検出
K-Means	kmeans	ノードプロパティでノードをクラスタリングする
三角形カウント	triangle_count	局所クラスタリング／密なサブグラフ
K-1 Coloring	k1coloring	隣接ノードの色が異なるように割り当てる（貪欲法、色数を抑制）

中心性

アルゴリズム	プロシージャ	使用例
PageRank	page_rank	影響力でノードをランク付けする
Article Rank	article_rank	次数の高い隣接ノードの重みを下げる PageRank の派生手法
Betweenness	betweenness	中継ノードを見つける
次数	degree	直接接続の数を数える

経路探索

アルゴリズム	プロシージャ	使用例
Dijkstra Source-Target	dijkstra	始点から終点（複数可）またはペアまでの最短経路
Dijkstra Single-Source	dijkstra_single_source	1 つのノードから他のすべてのノードまでの最短経路
Delta-Stepping SSSP	delta_stepping	並列の単一始点最短経路探索
幅優先探索	bfs	始点からの BFS 探索
Yen's K-Shortest Paths	yens	上位 K 個のループのない最短経路
Max Flow	max_flow	容量を考慮した最大フロー
Min-Cost Max Flow	max_flow_min_cost	合計コストを最小化する最大フロー
FastPath	fastpath	高速な近似最短経路探索

類似性

アルゴリズム	プロシージャ	使用例
Node Similarity	node_similarity	共通の隣接ノードに基づいて類似ノードを見つける
Filtered Node Similarity	node_similarity_filtered	始点／終点フィルターを使ったノード類似性
KNN	knn	最も類似する K 個のノード
Filtered KNN	knn_filtered	始点／終点フィルターを使った KNN

ノード埋め込み

アルゴリズム	プロシージャ	使用例
FastRP	fast_rp	高速なノード埋め込み
Node2Vec	node2vec	ランダムウォークによるノード埋め込み
HashGNN	hashgnn	トレーニング不要の GNN に着想を得た埋め込み

GraphSAGE（グラフ ML）

アルゴリズム	プロシージャ	使用例
ノード分類 — トレーニング	gs_nc_train	教師ありノードラベルモデルをトレーニングする
ノード分類 — 予測	gs_nc_predict	トレーニング済みモデルでラベルを予測する
教師なし埋め込み — トレーニング	gs_unsup_train	教師なし埋め込みモデルをトレーニングする
教師なし埋め込み — 予測	gs_unsup_predict	トレーニング済みモデルで埋め込みを推論する

モデルカタログ（GraphSAGE）

show_models、model_exists、drop_model。

---

アルゴリズム固有の注意事項

GraphSAGE

• GraphSAGE が使用する射影ノードテーブルには、ARRAY プロパティ列を含めないでください。複数値の数値特徴量には VECTOR(FLOAT, n) を使用してください。（GraphSAGE 以外のアルゴリズムでは ARRAY を使用できます。）
• 特徴量列は非 NULL かつ有限値である必要があります。ビュー内で NULL 許容の特徴量列をフィルタリング、補完、または除外してください。gs_nc_train の場合、targetProperty はラベル（特徴量ではありません）であり、NULL でもかまいません。
• 実行前に、GraphSAGE が各ノードテーブルで使用するノードプロパティを一覧表示してください。対象は NODEID 以外のすべての列です。gs_nc_train では targetProperty を除外してください。
• トレーニング（gs_nc_train、gs_unsup_train）には時間がかかる場合があり、GPU プール（GPU_NV_S）を使用することがあります。トレーニングを実行する前に、正確な CALL を提示し、明示的な確認を得てください。

Dijkstra 始点・終点（dijkstra）

次のいずれかを指定します。

• 単一のペア：sourceNode + sourceNodeTable、targetNode + targetNodeTable。
• 1 つの始点と複数の終点：sourceNode + sourceNodeTable、targetNodes（リスト）+ targetNodesTable。
• 複数のペア：sourceTargetNodePairsTable（SOURCENODEID／TARGETNODEID 列を含むテーブル）+ sourceNodeTable + targetNodeTable。

全般

• NODEID 自体をアルゴリズムプロパティとして使用しないでください。
• 値が NULL の設定パラメーターは省略してください。

---

インストール

1. Snowflake Marketplace から Neo4j Graph Analytics をインストールします（デフォルトのアプリ名は Neo4j_Graph_Analytics です）。
2. プロンプトが表示されたら、Event sharing を有効にします。
3. Data Products → Apps → Neo4j Graph Analytics → Privileges → Grant の順に進み、CREATE COMPUTE POOL と CREATE WAREHOUSE を付与してから、Activate をクリックします。

---

権限の設定

2 つのパートがあります。パート A（コンシューマーロール）は常に必要です。パート B は、データアクセスモードを必ず 1 つだけ選択します。併用しないでください。

モード	ジョブの実行主体	付与方法	使用する場合
アプリ ID（OAuth）— デフォルト	アプリケーション	直接付与 + アプリに付与されたデータベースロール	デフォルトです。最も簡単で、1 組の付与で全ユーザーをカバーします。
ユーザーとして実行 — プレビュー	登録済みロールを使用する呼び出し元ユーザー	アプリに GRANT CALLER / GRANT INHERITED CALLER を付与	QUERY_HISTORY でユーザーごとの帰属を確認し、ジョブに対してユーザーごとの認可を適用する必要がある場合。

ユーザーとしての実行は、セキュリティの強化ではなく、粒度の向上です。また、実際の運用負荷（PAT、SECRET、ユーザーごとの呼び出し元権限、トークンのローテーション）が増えます。デフォルトではアプリ ID を使用し、ユーザーごとの ID またはユーザーごとの認可をユーザーが明示的に求めた場合に限り、ユーザーとして実行する設定を行ってください。

パート A — コンシューマーロール（どちらのモードでも必要）

USE ROLE ACCOUNTADMIN;

-- Consumer role for app users
CREATE ROLE IF NOT EXISTS MY_CONSUMER_ROLE;
GRANT APPLICATION ROLE Neo4j_Graph_Analytics.app_user TO ROLE MY_CONSUMER_ROLE;
SET MY_USER = (SELECT CURRENT_USER());
GRANT ROLE MY_CONSUMER_ROLE TO USER IDENTIFIER($MY_USER);

-- Optional: admin role, needed for the app_admin procedures (compute pools, execute-as-user flag)
CREATE ROLE IF NOT EXISTS MY_ADMIN_ROLE;
GRANT APPLICATION ROLE Neo4j_Graph_Analytics.app_admin TO ROLE MY_ADMIN_ROLE;
GRANT ROLE MY_ADMIN_ROLE TO USER IDENTIFIER($MY_USER);

-- Let the consumer role read output tables
GRANT USAGE ON DATABASE MY_DATABASE TO ROLE MY_CONSUMER_ROLE;
GRANT USAGE ON SCHEMA MY_DATABASE.MY_SCHEMA TO ROLE MY_CONSUMER_ROLE;
GRANT SELECT ON FUTURE TABLES IN SCHEMA MY_DATABASE.MY_SCHEMA TO ROLE MY_CONSUMER_ROLE;

ACCOUNTADMIN にアプリケーションロールが暗黙的に付与されるわけではありません。preview.* および admin.* プロシージャには Neo4j_Graph_Analytics.app_admin を付与されたロールが必要です。アルゴリズムプロシージャおよび preview.register_user_role には app_user が必要です。

パート B、オプション 1 — アプリ ID の権限付与（デフォルト、データベース／スキーマごとに 1 回実行）

USE ROLE ACCOUNTADMIN;

-- Database role granting the app access to your data
USE DATABASE MY_DATABASE;
CREATE DATABASE ROLE IF NOT EXISTS MY_DB_ROLE;
GRANT USAGE ON DATABASE MY_DATABASE TO DATABASE ROLE MY_DB_ROLE;
GRANT USAGE ON SCHEMA MY_DATABASE.MY_SCHEMA TO DATABASE ROLE MY_DB_ROLE;
GRANT SELECT ON ALL TABLES  IN SCHEMA MY_DATABASE.MY_SCHEMA TO DATABASE ROLE MY_DB_ROLE;
GRANT SELECT ON ALL VIEWS   IN SCHEMA MY_DATABASE.MY_SCHEMA TO DATABASE ROLE MY_DB_ROLE;
-- FUTURE grants let the app read tables/views it creates (needed for chaining)
GRANT SELECT ON FUTURE TABLES IN SCHEMA MY_DATABASE.MY_SCHEMA TO DATABASE ROLE MY_DB_ROLE;
GRANT SELECT ON FUTURE VIEWS  IN SCHEMA MY_DATABASE.MY_SCHEMA TO DATABASE ROLE MY_DB_ROLE;
GRANT CREATE TABLE ON SCHEMA MY_DATABASE.MY_SCHEMA TO DATABASE ROLE MY_DB_ROLE;
GRANT DATABASE ROLE MY_DB_ROLE TO APPLICATION Neo4j_Graph_Analytics;

USE ROLE MY_CONSUMER_ROLE;   -- run algorithms as the consumer role

MY_DATABASE、MY_SCHEMA、MY_CONSUMER_ROLE、MY_DB_ROLE を、すべての箇所で実際の名前に置き換えてください。

パート B、オプション 2 — ユーザーとして実行（プレビュー）

ジョブは、呼び出し元ユーザーが保持するロールを使用し、呼び出し元の権限の範囲内で、Programmatic Access Token（PAT）によって呼び出し元ユーザーとして認証されます。プロシージャは <APP>.preview.* にあり、GA 前に変更される場合があります。

オンボーディングを最初から最後までスクリプト化することはできません。ADD PROGRAMMATIC ACCESS TOKEN で表示されるトークンシークレットは一度しか表示されません。パート 1 を実行し、ユーザーからトークンを受け取ってから、パート 2 を実行してください。

-- PART 1 — enable execute-as-user and mint the token
USE ROLE ACCOUNTADMIN;

-- Prerequisite: PATs require a network policy by default, else jobs fail with
-- "Fail : Network policy is required". This waives it; a user who already has a
-- network policy keeps it enforced. Authentication policies are schema-level objects.
USE SCHEMA MY_DATABASE.MY_SCHEMA;
CREATE AUTHENTICATION POLICY IF NOT EXISTS pat_no_network_required
    PAT_POLICY = (NETWORK_POLICY_EVALUATION = ENFORCED_NOT_REQUIRED);
ALTER USER <user_name> SET AUTHENTICATION POLICY pat_no_network_required;

-- Step 1: enable on the install — once per account, not per user. Needs app_admin,
-- which ACCOUNTADMIN does not hold implicitly.
USE ROLE MY_ADMIN_ROLE;
CALL Neo4j_Graph_Analytics.preview.set_enable_custom_credentials(TRUE);

-- Step 2a: mint a PAT bound to the role. ROLE_RESTRICTION is load-bearing — it pins
-- the PAT to this role whatever the app's registry says, and must match Step 2d.
USE ROLE ACCOUNTADMIN;
ALTER USER <user_name> ADD PROGRAMMATIC ACCESS TOKEN app_pat
    DAYS_TO_EXPIRY = 365
    ROLE_RESTRICTION = 'MY_CONSUMER_ROLE';

停止してください。 最後の結果セットにある token_secret 列を今すぐコピーしてください。Snowflake では再表示されません。下の SECRET_STRING に貼り付けてください。

-- PART 2, steps 2b + 2c — store the token, let the app read it. These are direct
-- grants, not caller grants: the app reads the secret as itself at job-start time.
USE ROLE ACCOUNTADMIN;
CREATE OR REPLACE SECRET MY_DATABASE.MY_SCHEMA.pat_secret_<user_name>
    TYPE = GENERIC_STRING                    -- GENERIC_STRING only; PASSWORD won't work
    SECRET_STRING = '<paste_token_secret_here>';
GRANT USAGE ON DATABASE MY_DATABASE TO APPLICATION Neo4j_Graph_Analytics;
GRANT USAGE ON SCHEMA MY_DATABASE.MY_SCHEMA TO APPLICATION Neo4j_Graph_Analytics;
GRANT READ ON SECRET MY_DATABASE.MY_SCHEMA.pat_secret_<user_name>
    TO APPLICATION Neo4j_Graph_Analytics;

-- Step 2d: register the user. Run in a session opened AS <user_name> so
-- CURRENT_USER() resolves to them, under a role holding app_user.
USE ROLE MY_CONSUMER_ROLE;
CALL Neo4j_Graph_Analytics.preview.register_user_role(
    'MY_CONSUMER_ROLE',                              -- = ROLE_RESTRICTION on the PAT
    'MY_DATABASE.MY_SCHEMA.pat_secret_<user_name>'   -- FQN of the SECRET
);

-- Step 2e: caller grants for the data the jobs read and write. Repeat per schema —
-- this is the only widening mechanism, and there is no FUTURE equivalent, so re-run
-- it after creating views or tables a later job needs to read.
USE ROLE ACCOUNTADMIN;
GRANT CALLER USAGE ON DATABASE MY_DATABASE TO APPLICATION Neo4j_Graph_Analytics;
GRANT CALLER USAGE ON SCHEMA MY_DATABASE.MY_SCHEMA TO APPLICATION Neo4j_Graph_Analytics;
GRANT CALLER CREATE TABLE ON SCHEMA MY_DATABASE.MY_SCHEMA TO APPLICATION Neo4j_Graph_Analytics;
GRANT INHERITED CALLER INSERT ON ALL TABLES IN SCHEMA MY_DATABASE.MY_SCHEMA TO APPLICATION Neo4j_Graph_Analytics;
GRANT INHERITED CALLER SELECT ON ALL TABLES IN SCHEMA MY_DATABASE.MY_SCHEMA TO APPLICATION Neo4j_Graph_Analytics;
GRANT INHERITED CALLER SELECT ON ALL VIEWS  IN SCHEMA MY_DATABASE.MY_SCHEMA TO APPLICATION Neo4j_Graph_Analytics;

管理者がユーザーに登録した内容を確認するには、次のようにします。

CALL Neo4j_Graph_Analytics.preview.get_user_role_registration('<user_name>');

ローテーションとロールバック：

-- Rotate: mint a new PAT, re-point the secret (its grants survive), drop the old PAT.
-- The registry needs no update — the SECRET name didn't change, only its value.
CREATE OR REPLACE SECRET MY_DATABASE.MY_SCHEMA.pat_secret_<user_name>
    TYPE = GENERIC_STRING SECRET_STRING = '<new_token_secret>';
ALTER USER <user_name> REMOVE PROGRAMMATIC ACCESS TOKEN <old_pat_name>;

-- Disable account-wide: app identity returns for everyone, registrations sit unused.
CALL Neo4j_Graph_Analytics.preview.set_enable_custom_credentials(FALSE);

-- Revoke a single user, leaving registry and SECRET intact:
REVOKE READ ON SECRET MY_DATABASE.MY_SCHEMA.pat_secret_<user_name>
    FROM APPLICATION Neo4j_Graph_Analytics;

-- ...or invalidate the credential outright:
ALTER USER <user_name> REMOVE PROGRAMMATIC ACCESS TOKEN app_pat;

---

よく使われるパターン

アルゴリズムの連結

結果はテーブルに書き込まれるため（また、FUTURE TABLES 権限によってアプリは作成したテーブルを読み取れます）、あるアルゴリズムの出力を次のアルゴリズムに渡します。

-- 1. Embeddings
CALL Neo4j_Graph_Analytics.graph.fast_rp('CPU_X64_XS', { ... });
-- 2. KNN over the embedding output table (projected as a node view)
CALL Neo4j_Graph_Analytics.graph.knn('CPU_X64_XS', { ... });

ユーザーとして実行するモードでは FUTURE 呼び出し元権限がありません。中間結果テーブルに対するプロジェクションビューを作成した後、次のアルゴリズムが読み取れるように、ステップ 2e の呼び出し元権限を再適用してください。

カテゴリデータを数値に変換する

グラフエンジンでは VARCHAR をプロパティとして使用できません。ビュー内でカテゴリを数値にマッピングしてください（例：CASE／ルックアップ結合）。元のラベルで結果を読み取るには、キーを使って出力テーブルをソーステーブルに結合します。

---

トラブルシューティング

問題	解決策
Insufficient privileges	アプリにはテーブル／ビューへの SELECT と、スキーマへの CREATE TABLE が必要です（「権限の設定」を参照）
no role registered for <user>	ユーザーとして実行が有効ですが、このユーザーはオンボーディングされていません。そのユーザーとして preview.register_user_role を実行してください（パート B のオプション 2、ステップ 2d）
Network policy is required	PAT ユーザーには、ネットワークポリシーなしで PAT を許可する認証ポリシーがありません。PAT_POLICY = (NETWORK_POLICY_EVALUATION = ENFORCED_NOT_REQUIRED) を指定してポリシーを適用してください
ユーザーとして実行するモードで does not exist or not authorized が表示される	データスキーマの呼び出し元権限が不足しているか、ON ALL ... 権限を付与した後にオブジェクトが作成されています。ステップ 2e を再実行してください
ユーザーとして実行するモードで書き込み時に Insufficient privileges to operate on table が表示される	書き込みスキーマに CALLER CREATE TABLE／INHERITED CALLER INSERT ON ALL TABLES がありません。ステップ 2e を再実行してください
USE ROLE not allowed／Current session is restricted	ロール制限付き PAT では想定される動作です。登録済みのプライマリロールからすべてにアクセスできる必要があります
ユーザーとして実行するモードで、認証時にジョブエラーが発生する	PAT の ROLE_RESTRICTION が登録済みロールと一致していないか、SECRET が TYPE = GENERIC_STRING ではありません
Column nodeId not found	ビューにキーがないか、キーのキャストが正しくありません。明示的なキャストを使って NODEID（および SOURCENODEID／TARGETNODEID）を公開してください
プロパティで型／プロジェクションエラーが発生する	プロパティ列がサポート対象の型にキャストされていません。キャストのルールを適用してください。リレーションシップのプロパティは BIGINT／DOUBLE／INT である必要があります
GraphSAGE が特徴量で失敗する	ARRAY 特徴量列を削除し（VECTOR を使用）、特徴量が NULL ではなく有限値であることを確認してください
Compute pool not available	プールの起動中の可能性があります。1 分待ってから再試行してください
アルゴリズムが結果を返さない	ノード／リレーションシップビューが空でないこと、およびすべての SOURCENODEID／TARGETNODEID が NODEID と一致することを確認してください

完全なガイド：https://neo4j.com/docs/snowflake-graph-analytics/current/troubleshooting/

---

さらに読む

• はじめに
• ジョブの実行 · スケールアウト · ジョブの見積もり
• すべてのアルゴリズム
• 管理 · ユーザーとして実行する認証
• Cortex Agent との統合
• TPC-H データを使ったバスケット分析の例

---

チェックリスト

• アプリをインストール済みで、コンシューマーロールを作成済み。データアクセス方式を1 つ（アプリ ID またはユーザーとして実行）設定済み
• ユーザーとして実行する場合：インストールフラグをオンにし、一致する ROLE_RESTRICTION を指定した PAT を発行し、アプリから SECRET を読み取り可能にし、ユーザーを登録し、呼び出し元に権限を付与済み
• ビューで NODEID／SOURCENODEID／TARGETNODEID を公開し、すべてのプロパティを明示的にキャスト済み
• orientation がアルゴリズムと一致
• エラーなく単一の CALL を実行し、出力テーブルにデータが格納済み
• 結果をソーステーブルに結合し、読みやすいラベルを表示