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. 投影 → 计算 → 写入 — 使用单个 CALL 运行算法，组合 project、compute 和 write 配置。
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 — 属性列绝不能直接写成 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 步——投影 → 计算 → 写入

每次运行都通过单个 CALL 完成，第一个参数是计算池，第二个参数是包含三个部分的 JSON 配置。注意，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 的二分图（两个互不相交的节点集合）；使用 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;

对于关系结果，请将源表连接两次 — 一次使用 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 着色	k1coloring	分配颜色，使相邻节点颜色不同（贪心算法，使用较少颜色）

中心性

算法	过程	用例
PageRank	page_rank	按影响力为节点排名
文章排名	article_rank	PageRank 变体，会降低高度节点邻居的权重
中介中心性	betweenness	查找桥接节点
度	degree	统计直接连接数

寻路

算法	过程	用例
Dijkstra 源点-目标点	dijkstra	查找从源点到目标点或目标点对的最短路径
Dijkstra 单源	dijkstra_single_source	查找从一个节点到所有其他节点的最短路径
Delta-Stepping 单源最短路径	delta_stepping	并行计算单源最短路径
广度优先搜索	bfs	从源点开始进行 BFS 遍历
Yen 的 K 条最短路径	yens	查找前 K 条无环最短路径
最大流	max_flow	计算带容量的最大流
最小费用最大流	max_flow_min_cost	计算总费用最低的最大流
FastPath	fastpath	快速近似最短路径

相似度

算法	过程	用例
节点相似度	node_similarity	根据共同邻居查找相似节点
过滤节点相似度	node_similarity_filtered	带源点 / 目标点筛选的节点相似度
KNN	knn	查找 K 个最相似的节点
过滤 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 且为有限值——在视图中过滤、填补或排除可空特征列。对于 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；
• 一个源节点，多个目标节点：sourceNode + sourceNodeTable、targetNodes（列表）+ targetNodesTable；
• 多个节点对：sourceTargetNodePairsTable（包含 SOURCENODEID/TARGETNODEID 列的表）+ sourceNodeTable + targetNodeTable。

通用规则

• 切勿将 NODEID 本身用作算法属性。
• 如果某个配置参数的值为 null，则省略该参数。

---

安装

1. 从 Snowflake Marketplace 安装 Neo4j Graph Analytics（默认应用名称为 Neo4j_Graph_Analytics）。
2. 出现提示时，启用事件共享。
3. Data Products → Apps → Neo4j Graph Analytics → Privileges → Grant：授予 CREATE COMPUTE POOL 和 CREATE WAREHOUSE，然后点击 Activate。

---

权限设置

分为两部分。A 部分（使用方角色）始终必需。B 部分是在恰好一种数据访问模式中二选一——不要混用。

模式	作业以何种身份运行	授权方式	适用场景
应用身份（OAuth）— 默认	应用	直接授权 + 授予应用的数据库角色	默认模式。最简单，一组授权适用于所有用户。
以用户身份执行 — 预览版	调用用户，在已注册角色下运行	向应用授予 GRANT CALLER / GRANT INHERITED CALLER	需要在 QUERY_HISTORY 中按用户归属查询，并对作业实施按用户授权。

以用户身份执行是对粒度的提升，而不是安全性提升；它还会增加实际运维负担（PAT、SECRET、每个用户的调用方授权，以及令牌轮换）。默认使用应用身份；仅当用户明确要求按用户区分身份或授权时，才设置以用户身份执行。

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 — 应用身份授权（默认，每个数据库/架构运行一次）

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 — 以用户身份执行（预览版）

作业使用调用用户的程序化访问令牌（PAT）进行身份验证，并在该用户持有的角色下运行，权限受调用方授权限制。过程位于 <APP>.preview.* 中，正式发布前可能会发生变化。

无法通过脚本端到端完成用户接入：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	池可能仍在启动；等待一分钟后重试
算法未返回结果	检查节点/关系视图是否为空，并确保每个 SOURCENODEID/TARGETNODEID 都与某个 NODEID 匹配

完整指南：https://neo4j.com/docs/snowflake-graph-analytics/current/troubleshooting/

---

延伸阅读

• 入门指南
• 运行作业 · 横向扩展 · 作业估算
• 所有算法
• 管理 · 以用户身份执行的身份验证
• 与 Cortex Agent 集成
• TPC-H 数据上的购物篮分析示例

---

检查清单

• 已安装应用；已创建使用者角色；已设置一种数据访问模式（应用身份或以用户身份执行）
• 如果以用户身份执行：已启用安装标志；已创建具有匹配 ROLE_RESTRICTION 的 PAT；应用可读取 SECRET；已注册用户；已授予调用方所需权限
• 视图公开 NODEID / SOURCENODEID / TARGETNODEID，且每个属性都已显式转换类型
• orientation 与算法匹配
• 单次 CALL 运行无错误；输出表已填充
• 已将结果与源表联接，以显示易读的标签