graph-viewer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Graph Viewer

图形查看器

Use This When

适用场景

The user wants to embed an interactive graph of a CDF data model — nodes, direct relations, edges, and reverse relations — inside a Dune app.

Do not use this skill for static diagrams, pure dataflow visualizations, or non-CDF graphs.

用户希望在Dune应用中嵌入CDF数据模型的交互式图形——包含节点、直接关联、边和反向关联。

请勿将此技能用于静态图表、纯数据流可视化或非CDF图形。

Prerequisites

前置条件

The app is wrapped in
```
@cognite/dune
```
's
```
<DuneProvider>
```
so
```
useDune()
```
returns an authenticated SDK.
The target data model exists in CDF and you know its
```
space
```
,
```
externalId
```
, and
```
version
```
.
The app uses React 18+ and TypeScript.

应用已被
```
@cognite/dune
```
的
```
<DuneProvider>
```
包裹，确保
```
useDune()
```
能返回已认证的SDK。
目标数据模型已存在于CDF中，且你知晓其
```
space
```
、
```
externalId
```
和
```
version
```
。
应用使用React 18+和TypeScript。

Integration Workflow

集成流程

Follow these steps in order. Adapt to the target repo's conventions instead of inventing new ones.

Inspect the target app. Read
```
package.json
```
and look at the existing folder structure (e.g.
```
src/features/*
```
,
```
src/components/*
```
, path aliases like
```
@/*
```
).
Install missing dependencies with the app's package manager (
```
npm
```
,
```
pnpm
```
,
```
yarn
```
, …). See the Dependencies table below for purposes and suggested versions. Reuse the React version already pinned by the app rather than upgrading it, and prefer any versions the repo already pins over the suggestions here.
Copy the bundle into the app. Copy every file from
```
skills/graph-viewer/code/
```
into an app-local feature folder, for example:
text
```
src/features/graph-viewer/
```
If the repo already has a different feature/components layout or alias, mirror it.

Import from the local folder, never from

@skills/...

. With a typical

@/*

alias:

tsx

import { useGraphViewer } from "@/features/graph-viewer";

Render
GraphCanvas
inside a container with explicit dimensions (height is required — see the minimal example below).
Run typecheck and build (
```
tsc --noEmit
```
,
```
npm run build
```
, etc.) and fix any path or type issues introduced by the copy.

按以下顺序执行步骤，需适配目标仓库的约定，而非自行创建新规则。

检查目标应用：阅读
```
package.json
```
并查看现有文件夹结构（如
```
src/features/*
```
、
```
src/components/*
```
、
```
@/*
```
这类路径别名）。
安装缺失依赖：使用应用的包管理器（
```
npm
```
、
```
pnpm
```
、
```
yarn
```
等）安装。下方依赖表格列出了用途和建议版本。优先复用应用已锁定的React版本，而非升级；若仓库已锁定其他依赖版本，优先使用仓库版本而非此处建议版本。
复制代码包到应用：将
```
skills/graph-viewer/code/
```
下的所有文件复制到应用本地的功能文件夹中，例如：
text
```
src/features/graph-viewer/
```
若仓库已有不同的功能/组件布局或别名，请保持一致。
从本地文件夹导入，切勿从
```
@skills/...
```
导入。使用典型的
```
@/*
```
别名示例：
tsx
```
import { useGraphViewer } from "@/features/graph-viewer";
```
在具有明确尺寸的容器内渲染
GraphCanvas
（高度为必填项——见下方最简示例）。
运行类型检查和构建（
```
tsc --noEmit
```
、
```
npm run build
```
等），修复复制过程中引入的路径或类型问题。

Minimal Example

最简示例

tsx

import { useGraphViewer } from "@/features/graph-viewer";

export function GraphPanel() {
  const { GraphCanvas, isLoading, error } = useGraphViewer({
    dataModel: { space: "my-space", externalId: "my-data-model", version: "1" },
    instance: { space: "my-instance-space", externalId: "pump-001" },
  });

  if (isLoading) return <div>Loading graph…</div>;
  if (error) return <div>Error: {error}</div>;

  return <GraphCanvas className="h-[600px] w-full" />;
}

tsx

import { useGraphViewer } from "@/features/graph-viewer";

export function GraphPanel() {
  const { GraphCanvas, isLoading, error } = useGraphViewer({
    dataModel: { space: "my-space", externalId: "my-data-model", version: "1" },
    instance: { space: "my-instance-space", externalId: "pump-001" },
  });

  if (isLoading) return <div>加载图形中…</div>;
  if (error) return <div>错误：{error}</div>;

  return <GraphCanvas className="h-[600px] w-full" />;
}

Dependencies

依赖

Suggested versions reflect the latest published majors at the time of writing. They are starting points — if the target app already pins different versions, defer to the app.

Package	Suggested version	Purpose
`react`	`^18.2.0`	UI framework (peer; reuse the app's version)
`@cognite/sdk`	`^10.10.0`	CDF API client (instances, data models)
`@cognite/dune`	`^2.1.0`	Provides the authenticated SDK via `useDune()`
`reagraph`	`^4.30.8`	WebGL graph rendering engine
`lucide-react`	`^1.14.0`	Icon set used by the node-type legend

Example install (npm; adapt to the app's package manager):

bash

npm install @cognite/sdk@^10.10.0 @cognite/dune@^2.1.0 reagraph@^4.30.8 lucide-react@^1.14.0

建议版本为撰写本文时最新的主版本，仅作为起点——若目标应用已锁定不同版本，请以应用版本为准。

包名	建议版本	用途
`react`	`^18.2.0`	UI框架（对等依赖；复用应用已有的版本）
`@cognite/sdk`	`^10.10.0`	CDF API客户端（实例、数据模型）
`@cognite/dune`	`^2.1.0`	通过 `useDune()` 提供已认证的SDK
`reagraph`	`^4.30.8`	WebGL图形渲染引擎
`lucide-react`	`^1.14.0`	节点类型图例使用的图标集

安装示例（npm；请适配应用的包管理器）：

bash

npm install @cognite/sdk@^10.10.0 @cognite/dune@^2.1.0 reagraph@^4.30.8 lucide-react@^1.14.0

CDF Cost & Performance

CDF成本与性能

Graph expansion can issue many CDF requests, especially with reverse relations. For large or unfamiliar data models, be conservative:

Set
```
whitelistedRelationProps
```
to the few properties the app actually needs to traverse.
Lower
```
initialConnectionLimit
```
(it is a hard maximum of connections fetched per expansion).
Lower
```
maxNodes
```
to bound the in-memory LRU buffer.
Only declare
```
coreReverseQueries
```
for relations the app must surface; each entry adds an extra query per expansion.

Tuples in

coreReverseQueries

are version-aware:

[space, viewExternalId, viewVersion, propertyName, isList]

图形展开可能会发起大量CDF请求，尤其是包含反向关联时。对于大型或不熟悉的数据模型，请谨慎配置：

将
```
whitelistedRelationProps
```
设置为应用实际需要遍历的少量属性。
降低
```
initialConnectionLimit
```
（这是每次展开时获取连接的硬上限）。
降低
```
maxNodes
```
以限制内存中的LRU缓冲区。
仅为应用必须展示的关联声明
```
coreReverseQueries
```
；每个条目会在每次展开时增加额外查询。

coreReverseQueries

中的元组支持版本感知：

[space, viewExternalId, viewVersion, propertyName, isList]

。

Advanced Reference

高级参考

For full configuration tables, return-value docs, layouts, theming, and richer examples, read

code/README.md

For implementation details, inspect the source files under

code/

如需完整的配置表、返回值文档、布局、主题设置及更丰富的示例，请阅读

code/README.md

。

如需了解实现细节，请查看

code/

下的源文件。

Verification Checklist

验证清单

The app is wrapped in
```
<DuneProvider>
```
.
All files from
```
skills/graph-viewer/code/
```
were copied into an app-local folder.
Imports point to the app-local folder (e.g.
```
@/features/graph-viewer
```
), not
```
@skills/...
```
.

@cognite/dune

@cognite/sdk

reagraph

, and

lucide-react

are present in

package.json

The container that renders
```
<GraphCanvas>
```
has an explicit height.
```
tsc --noEmit
```
and the app's build both pass.
No references to
```
dune-industrial-components
```
were introduced.

应用已用
```
<DuneProvider>
```
包裹。
```
skills/graph-viewer/code/
```
下的所有文件已复制到应用本地文件夹。
导入指向应用本地文件夹（如
```
@/features/graph-viewer
```
），而非
```
@skills/...
```
。

package.json

中已包含

@cognite/dune

、

@cognite/sdk

、

reagraph

和

lucide-react

。

渲染
```
<GraphCanvas>
```
的容器具有明确高度。
```
tsc --noEmit
```
和应用构建均通过。
未引入任何
```
dune-industrial-components
```
相关引用。