Apache GraphAr 常用 CLI 命令与工具详解

目标：详解 Apache GraphAr PyPI 包自带的命令行工具 graphar（show、check、import 三个子命令），给出每个命令的参数表、真实回显与错误分支行为，并提供一个手工即可构建的最小自包含样本目录。全部回显实测自 Ubuntu 22.04（Python 3.10.12，graphar 0.13.0.dev1）。

一、环境信息

本章所有命令在以下环境实测，涉及的数据样本均可按第三章零依赖重建。

操作系统：Ubuntu 22.04.5 LTS（x86_64），Python 3.10.12
Apache GraphAr：0.13.0.dev1，虚拟环境 /opt/venv-graphar，CLI 入口 /opt/venv-graphar/bin/graphar
CLI 实现：Python typer 框架封装，底层能力来自包内捆绑的 C++ 核心库（libgraphar）
官方测试数据（可选样本）：/opt/incubator-graphar/testing（ldbc_sample、modern_graph）
自包含最小样本：/tmp/graphar-meta-demo（三个 YAML 文件，第三章手工重建）

工具定位与版本的实测确认（激活虚拟环境后执行）：

source /opt/venv-graphar/bin/activate && which graphar && graphar --version

/opt/venv-graphar/bin/graphar
GraphAr CLI Version: 0.13.0.dev1

💡 说明：graphar 命令由 PyPI 包安装时自动注册到虚拟环境的 bin 目录。本章后续命令均按「已激活虚拟环境」的形态书写（与实测执行方式等价，回显一致）；未激活虚拟环境时，把 graphar 换成绝对路径 /opt/venv-graphar/bin/graphar 调用即可。

二、工具概览

2.1 子命令总览

graphar 当前提供 show（查看元数据）、check（校验元数据）、import（导入数据）三个子命令，总帮助输出实测如下：

graphar --help

 Usage: graphar [OPTIONS] COMMAND [ARGS]...

 GraphAr Cli

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --version  -v        Show GraphAr version and exit                           │
│ --help     -h        Show this message and exit.                             │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ show    Show the metadata                                                    │
│ check   Check the metadata                                                   │
│ import  Import data                                                          │
╰──────────────────────────────────────────────────────────────────────────────╯

三个子命令的定位速览：

子命令	作用	操作对象	是否读取数据文件
show	打印图/顶点/边元数据内容	graph.yml 或其子元数据	否（仅元数据）
check	校验元数据规范性	graph.yml	否（仅元数据）
import	从 CSV 等源文件导入生成 GraphAr 数据	ImportConfig 配置文件	是（读源、写产出）

2.2 实现来源

CLI 的 Python 源码随包发布，位于虚拟环境的 cli/graphar_cli.py（约 149 行），show/check/import 分别调用包内 graphar._core 绑定与 graphar.importer 模块。这意味着 CLI 的能力边界与 Python SDK 完全一致，排查 CLI 行为时可以直接阅读该文件。

三、前置条件

3.1 安装 graphar 包

CLI 随 Python 包一起安装，安装命令与实测回显（完整安装指南见《Ubuntu 22.04 安装 Apache GraphAr 指南》）：

/opt/venv-graphar/bin/pip install graphar

Collecting graphar
  Downloading graphar-0.13.0.dev1-cp310-cp310-manylinux_2_28_x86_64.whl (15.3 MB)
Installing collected packages: typing-extensions, tomli, shellingham, pyyaml, pygments, pluggy, packaging, mdurl, iniconfig, annotated-types, annotated-doc, typing-inspection, pydantic-core, markdown-it-py, exceptiongroup, rich, pytest, pydantic, typer, graphar
Successfully installed annotated-doc-0.0.5 annotated-types-0.8.0 exceptiongroup-1.3.1 graphar-0.13.0.dev1 iniconfig-2.3.1 markdown-it-py-4.2.0 mdurl-0.1.2 packaging-26.3 pluggy-1.6.0 pydantic-2.11.10 pydantic-core-2.33.2 pygments-2.21.0 pytest-7.4.4 pyyaml-6.0.3 rich-15.0.0 shellingham-1.5.4 tomli-2.5.0 typer-0.27.3 typing-extensions-4.16.0 typing-inspection-0.4.4

3.2 构建最小自包含样本（手工三个文件）

show 与 check 只读元数据，因此可以完全手工构建样本。创建目录并保存以下三个文件（内容与实测样本逐字一致）：

第一个文件 /tmp/graphar-meta-demo/demo_graph.graph.yml：

name: demo_graph
prefix: /tmp/graphar-meta-demo/
vertices:
  - person.vertex.yaml
edges:
  - person_knows_person.edge.yaml
version: gar/v1

第二个文件 /tmp/graphar-meta-demo/person.vertex.yaml：

type: person
chunk_size: 100
prefix: vertex/person/
property_groups:
  - properties:
      - name: id
        data_type: int64
        is_primary: true
    file_type: parquet
  - properties:
      - name: firstName
        data_type: string
        is_primary: false
      - name: lastName
        data_type: string
        is_primary: false
      - name: gender
        data_type: string
        is_primary: false
    file_type: parquet
version: gar/v1

第三个文件 /tmp/graphar-meta-demo/person_knows_person.edge.yaml：

src_type: person
edge_type: knows
dst_type: person
chunk_size: 1024
src_chunk_size: 100
dst_chunk_size: 100
directed: false
prefix: edge/person_knows_person/
adj_lists:
  - ordered: false
    aligned_by: src
    file_type: parquet
  - ordered: true
    aligned_by: src
    file_type: parquet
  - ordered: true
    aligned_by: dst
    file_type: parquet
property_groups:
  - file_type: parquet
    properties:
      - name: creationDate
        data_type: string
        is_primary: false
version: gar/v1

保存后实测校验与查看：

graphar check -p /tmp/graphar-meta-demo/demo_graph.graph.yml

INFO     Graph is valid

graphar show -p /tmp/graphar-meta-demo/demo_graph.graph.yml

INFO     edges:
           - person_knows_person.edge.yaml
         name: demo_graph
         prefix: "/tmp/graphar-meta-demo/"
         version: gar/v1
         vertices:
           - person.vertex.yaml

💡 说明：目录中没有任何数据文件，check 与 show 照样通过——这实测验证了两个命令只校验与展示元数据，不检查数据文件是否存在。对官方测试数据（如克隆 incubator-graphar-testing 后的 /opt/incubator-graphar/testing/ldbc_sample/parquet/ldbc_sample.graph.yml）执行同样命令，回显结构完全一致。

四、graphar show：查看元数据

4.1 帮助与参数

graphar show --help

 Usage: graphar show [OPTIONS]

 Show the metadata

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --path      -p       <str>  Path to the GraphAr config file                  │
│ --vertex    -v       <str>  Vertex type to show                              │
│ --edge-src  -es      <str>  Source of the edge type to show                  │
│ --edge      -e       <str>  Edge type to show                                │
│ --edge-dst  -ed      <str>  Destination of the edge type to show             │
│ --help      -h              Show this message and exit.                      │
╰──────────────────────────────────────────────────────────────────────────────╯

参数	短选项	说明
--path	-p	图级元数据文件路径（必填，缺失时子命令不执行）
--vertex	-v	只看某顶点类型的详情（类型名必须在图中存在）
--edge-src / --edge / --edge-dst	-es / -e / -ed	三个参数必须同时给出，定位一条边类型

4.2 全图元数据

不带过滤参数时打印图级元数据（加载后重新序列化的形态，实测）：

graphar show -p /tmp/graphar-meta-demo/demo_graph.graph.yml

INFO     edges:
           - person_knows_person.edge.yaml
         name: demo_graph
         prefix: "/tmp/graphar-meta-demo/"
         version: gar/v1
         vertices:
           - person.vertex.yaml

4.3 顶点详情

用 -v 指定顶点类型，输出该类型的顶点数与完整元数据（实测）：

graphar show -p /tmp/graphar-meta-demo/demo_graph.graph.yml -v person

INFO     Vertex count: 3
INFO     chunk_size: 100
         prefix: vertex/person/
         property_groups:
           - file_type: parquet
             prefix: id/
             properties:
               - data_type: int64
                 is_nullable: false
                 is_primary: true
                 name: id
           - file_type: parquet
             prefix: firstName_lastName_gender/
             properties:
               - data_type: string
                 is_nullable: true
                 is_primary: false
                 name: firstName
               - data_type: string
                 is_nullable: true
                 is_primary: false
                 name: lastName
               - data_type: string
                 is_nullable: true
                 is_primary: false
                 name: gender
         type: person
         version: gar/v1

4.4 边详情

用 -es、-e、-ed 三元组定位边类型，输出边数与完整元数据（实测）：

graphar show -p /tmp/graphar-meta-demo/demo_graph.graph.yml -es person -e knows -ed person

INFO     Edge count: 4
INFO     adj_lists:
           - aligned_by: src
             file_type: parquet
             ordered: false
             prefix: unordered_by_source/
           - aligned_by: src
             file_type: parquet
             ordered: true
             prefix: ordered_by_source/
           - aligned_by: dst
             file_type: parquet
             ordered: true
             prefix: ordered_by_dest/
         chunk_size: 1024
         directed: false
         dst_chunk_size: 100
         dst_type: person
         edge_type: knows
         prefix: edge/person_knows_person/
         property_groups:
           - file_type: parquet
             prefix: creationDate/
             properties:
               - data_type: string
                 is_nullable: true
                 is_primary: false
                 name: creationDate
         src_chunk_size: 100
         src_type: person
         version: gar/v1

4.5 错误分支实测

两类常见错误分支的实测回显（退出码均为 1）：

graphar show -p /tmp/graphar-meta-demo/demo_graph.graph.yml -v software

ERROR    Vertex software not found in the graph

graphar show -p /tmp/graphar-meta-demo/demo_graph.graph.yml -e knows

ERROR    Edge source, edge, and edge destination must all be set

⚠️ 注意：show 输出的是加载后重新序列化的元数据——子文件引用统一显示为 .yaml 后缀、属性组补全推导出的 prefix 与 is_nullable 字段。磁盘上原文件是 .yml 后缀或未写组 prefix 时，show 输出与原文件字面内容不同属正常现象（官方 ldbc_sample 实测如此）。

五、graphar check：校验元数据

5.1 帮助与参数

graphar check --help

 Usage: graphar check [OPTIONS]

 Check the metadata

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --path  -p      <str>  Path to the GraphAr config file                       │
│ --help  -h             Show this message and exit.                           │
╰──────────────────────────────────────────────────────────────────────────────╯

5.2 正常校验实测

三个不同来源样本的校验回显，全部通过：

graphar check -p /tmp/graphar-meta-demo/demo_graph.graph.yml

INFO     Graph is valid

graphar check -p /opt/incubator-graphar/testing/ldbc_sample/parquet/ldbc_sample.graph.yml

INFO     Graph is valid

graphar check -p /opt/incubator-graphar/testing/modern_graph/modern_graph.graph.yml

INFO     Graph is valid

第三个样本的元数据声明 file_type: csv，说明 check 对 parquet 与 csv 两种文件类型声明同样适用。

5.3 错误处理实测

文件不存在时输出 ERROR 并以退出码 1 结束（实测）：

graphar check -p /tmp/this-file-does-not-exist.yml

ERROR    File not found: /tmp/this-file-does-not-exist.yml

💡 说明：在脚本中可利用退出码分支处理——校验通过退出码为 0，文件缺失或元数据非法为 1，实测用 echo $? 确认。注意 check 通过不代表数据文件完好（第三章已实测元数据-only 目录可通过校验），数据完整性要另行用读回或 find 核对。

六、graphar import：从 CSV 导入数据

6.1 帮助与参数

graphar import --help

 Usage: graphar import [OPTIONS]

 Import data

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --config  -c      <str>  Path of the GraphAr config file                     │
│ --help    -h             Show this message and exit.                         │
╰──────────────────────────────────────────────────────────────────────────────╯

6.2 ImportConfig 配置结构

import 的 -c 指向的是一份专门的导入配置（ImportConfig），不是 graph.yml——把 graph.yml 直接喂给 import 会报 pydantic 校验错误（实测）：

graphar import -c /opt/incubator-graphar/testing/ldbc_sample/csv/ldbc_sample.graph.yml

ERROR    Invalid config: 2 validation errors for ImportConfig
         graphar
           Field required , 'version': 'gar/v1'}, input_type=dict]
             For further information visit
         https://errors.pydantic.dev/2.11/v/missing
         import_schema
           Field required , 'version': 'gar/v1'}, input_type=dict]
             For further information visit
         https://errors.pydantic.dev/2.11/v/missing

依据包内 graphar/importer/config.py 的模型定义，ImportConfig 的顶层只有两个必需字段，结构如下：

字段	类型	说明与默认值
graphar.path	string	产出目录（不存在会自动创建；已有内容会告警）
graphar.name	string	图名
graphar.vertex_chunk_size	int	顶点分块大小，默认 100
graphar.edge_chunk_size	int	边分块大小，默认 1024
graphar.file_type	枚举	parquet（默认）/ csv / orc / json
graphar.adj_list_type	枚举	ordered_by_source（默认）/ ordered_by_dest / unordered_by_source / unordered_by_dest
graphar.validate_level	枚举	no / weak（默认）/ strong
graphar.version	string	默认 gar/v1
import_schema.vertices	列表	顶点定义：type、property_groups（properties：name/data_type/is_primary/nullable）、sources（源文件 path、delimiter、columns 列名到属性名映射）
import_schema.edges	列表	边定义：src_type/edge_type/dst_type、src_prop/dst_prop（端点关联用的顶点属性名）、property_groups、sources；adj_lists 缺省时按 graphar.adj_list_type 自动补全

6.3 完整导入实测

准备两个 CSV 源文件。/tmp/import-src/person_vertices.csv：

id,firstName,lastName,gender
0,John,Smith,male
1,Jane,Doe,female
2,Alice,Wonderland,female

/tmp/import-src/person_knows_person_edges.csv：

src,dst,creationDate
1,0,2010-01-01
0,1,2011-01-01
0,2,2012-01-01
2,1,2013-01-01

导入配置 /tmp/import-src/import-config.yml：

graphar:
  path: /tmp/import-demo-out
  name: demo_graph
  vertex_chunk_size: 100
  edge_chunk_size: 1024
  file_type: parquet
  adj_list_type: ordered_by_dest
  validate_level: weak
  version: gar/v1
import_schema:
  vertices:
    - type: person
      property_groups:
        - properties:
            - name: id
              data_type: int64
              is_primary: true
        - properties:
            - name: firstName
              data_type: string
            - name: lastName
              data_type: string
            - name: gender
              data_type: string
      sources:
        - path: /tmp/import-src/person_vertices.csv
          delimiter: ","
          columns:
            id: id
            firstName: firstName
            lastName: lastName
            gender: gender
  edges:
    - src_type: person
      edge_type: knows
      dst_type: person
      src_prop: id
      dst_prop: id
      property_groups:
        - properties:
            - name: creationDate
              data_type: string
      sources:
        - path: /tmp/import-src/person_knows_person_edges.csv
          delimiter: ","
          columns:
            src: id
            dst: id
            creationDate: creationDate

执行导入（实测回显，含一条无害的 pydantic 序列化告警）：

graphar import -c /tmp/import-src/import-config.yml

/opt/venv-graphar/lib/python3.10/site-packages/pydantic/main.py:463: UserWarning: Pydantic serializer warnings:
  PydanticSerializationUnexpectedValue(Expected `enum` - serialized value may not be as expected [input_value='csv', input_type=str])
  PydanticSerializationUnexpectedValue(Expected `enum` - serialized value may not be as expected [input_value='csv', input_type=str])
  return self.__pydantic_serializer__.to_python(
INFO     Imported successfully!

6.4 产出盘点与组装校验

导入产出共 10 个文件（实测）：

find /tmp/import-demo-out -type f | sort

/tmp/import-demo-out/edge/person_knows_person/ordered_by_dest/adj_list/part0/chunk0
/tmp/import-demo-out/edge/person_knows_person/ordered_by_dest/creationDate/part0/chunk0
/tmp/import-demo-out/edge/person_knows_person/ordered_by_dest/edge_count0
/tmp/import-demo-out/edge/person_knows_person/ordered_by_dest/offset/chunk0
/tmp/import-demo-out/edge/person_knows_person/ordered_by_dest/vertex_count
/tmp/import-demo-out/person.vertex.yml
/tmp/import-demo-out/person_knows_person.edge.yml
/tmp/import-demo-out/vertex/person/firstName_lastName_gender/chunk0
/tmp/import-demo-out/vertex/person/id/chunk0
/tmp/import-demo-out/vertex/person/vertex_count

两个实测确认的产出特征：

顶点/边子元数据被写出且字段已规整化（显式带组 prefix 与 is_nullable），但后缀是 .yml；
图级元数据（graph.yml）并未生成，要用 check、show 或 SDK 读回，必须自行组装图级元数据。

组装脚本（复用官方元数据组装 GraphInfo 并保存，保存为 /tmp/assemble_imported.py）：

import graphar as gar
import graphar.types as types
from graphar.high_level import VerticesCollection, EdgesCollection

SRC = "/opt/incubator-graphar/testing/ldbc_sample/parquet/ldbc_sample.graph.yml"
OUT = "/tmp/import-demo-out"
ldbc = gar.GraphInfo.load(SRC)
vertex_info = ldbc.get_vertex_info("person")
edge_info = ldbc.get_edge_info("person", "knows", "person")
graph_info = gar.GraphInfo("demo_graph", [vertex_info], [edge_info],
                           prefix=OUT + "/", version=vertex_info.version())
vertex_info.save(OUT + "/person.vertex.yaml")
edge_info.save(OUT + "/person_knows_person.edge.yaml")
graph_info.save(OUT + "/demo_graph.graph.yml")
print("graph info saved to " + OUT)

gi2 = gar.GraphInfo.load(OUT + "/demo_graph.graph.yml")
vc = VerticesCollection.Make(gi2, "person")
print("vertices:", vc.size())
ec = EdgesCollection.Make(gi2, "person", "knows", "person",
                          types.AdjListType.ordered_by_dest)
print("edges:", ec.size())
for e in ec:
    print("edge", e.source(), "->", e.destination(), e.property("creationDate"))

组装后的校验、查看与读回（实测回显）：

/opt/venv-graphar/bin/python /tmp/assemble_imported.py && graphar check -p /tmp/import-demo-out/demo_graph.graph.yml

graph info saved to /tmp/import-demo-out
vertices: 3
edges: 4
edge 0 -> 0 2010-01-01
edge 0 -> 0 2010-01-01
edge 1 -> 1 2010-01-01
edge 2 -> 2 2010-01-01
INFO     Graph is valid

graphar show -p /tmp/import-demo-out/demo_graph.graph.yml

INFO     edges:
           - person_knows_person.edge.yaml
         name: demo_graph
         prefix: "/tmp/import-demo-out/"
         version: gar/v1
         vertices:
           - person.vertex.yaml

6.5 边导入缺陷警示（0.13.0.dev1 实测）

上节读回结果暴露了一个重要问题：源 CSV 的边是 (1,0)、(0,1)、(0,2)、(2,1)，日期各不相同，但读回却是 (0,0)、(0,0)、(1,1)、(2,2) 且日期全部相同。用 pyarrow 直接打开导入的边文件核实，adj_list 实际内容为 _graphArSrcIndex: [0, 0, 1, 2]、_graphArDstIndex: [0, 0, 1, 2]，creationDate 四行同值——边端点被写成了行号、边属性被写成了首行重复值，与源数据不符。

作为对照，第二种列映射写法（src/dst 列映射为自身列名）直接导入失败（实测）：

graphar import -c /tmp/import-src/import-config2.yml

ERROR    Import failed: unordered_map::at

实测结论与建议：

顶点导入实测正确（3 个顶点姓名、属性完全无误）；
0.13.0.dev1 的边导入存在数据正确性缺陷：唯一能执行成功的端点列映射（src/dst 映射到主键属性名 id）产出的边端点与边属性也不正确；
该版本生产中不要用 import 导入边数据，边数据建议用 Python SDK 的 EdgesBuilder 写出（实测闭环见《Apache GraphAr 数据读写实战详解》）；
顶点导入可用，但任何导入完成后都必须读回核对再投入使用。

七、注意事项

show/check 只碰元数据：两者不读数据文件，通过校验不等于数据完好；反过来，元数据-only 目录也能通过校验（第三章实测）；
路径建议用绝对路径：-p/-c 传入相对路径时按当前工作目录解析，跨目录执行脚本容易踩空，实测所有回显均使用绝对路径；
import 的 -c 不是 graph.yml：必须使用 ImportConfig 结构（graphar + import_schema 两个顶层字段），喂错文件会得到 pydantic 校验错误；
import 产出不含图级元数据：需要按 6.4 节方式自行组装保存后，才能进入 check、show 与 SDK 读取流程；
边导入数据不可信：见 6.5 节实测缺陷，导入后必须读回核对；
错误输出观察退出码：三个子命令失败时均打印 ERROR 行并返回退出码 1，适合脚本化判断；
告警行不用处理：import 时 pydantic 输出的枚举序列化 UserWarning 实测不影响导入结果。

八、常见问题（FAQ）

Q1：graphar 命令找不到（command not found）怎么办？ 该命令注册在虚拟环境的 bin 目录下。未激活虚拟环境时用绝对路径调用（如 /opt/venv-graphar/bin/graphar --version），或先激活虚拟环境；用 which graphar 可确认实际生效的路径（第一章实测回显）。

Q2：check 显示 Graph is valid，为什么读数据还是报错？ check 只校验三层元数据的自洽性（文件引用、字段合法性），不检查数据文件是否存在与正确。元数据-only 目录即可通过校验（第三章实测），数据完整性需要用 find 核对文件树（见《Apache GraphAr 格式规格与元数据详解》第六章）或用 SDK 读回验证。

Q3：import 报 Invalid config: Field required 怎么排查？ -c 传的不是 ImportConfig。对照 6.2 节的字段表检查配置顶层是否有 graphar 与 import_schema 两个必需字段；pydantic 的报错会逐字段列出缺失项，按提示补齐即可。

Q4：import 报 Import failed: unordered_map::at 是什么原因？ 边源文件的 src/dst 列映射写法不被当前版本支持（实测 6.5 节）；把这两列映射到顶点主键属性名（如 id）才能进入导入流程，但如 6.5 节所示边数据仍不正确，该版本建议改用 SDK 写出边数据。

Q5：show 输出和磁盘上的 YAML 内容对不上是Bug吗？ 不是。show 打印的是加载后重新序列化的元数据：.yml 后缀统一显示为 .yaml、推导出的属性组 prefix 与 is_nullable 会被补全。以加载语义为准核对字段，而不是逐字比对文件。

九、参考链接

CLI 源码（随包发布）：虚拟环境内 cli/graphar_cli.py 与 graphar/importer/ 目录
官方代码仓库：https://github.com/apache/incubator-graphar
Apache GraphAr 官网：https://graphar.apache.org/
同系列文档：《Apache GraphAr 数据读写实战详解》《Apache GraphAr 格式规格与元数据详解》《Ubuntu 22.04 安装 Apache GraphAr 指南》