Querying Art Blocks Data

When to Use GraphQL vs Domain Tools

The domain-specific tools cover most use cases and are easier to use:

Need	Tool
Browse/search projects	INLINECODE0
Full project details

Use the GraphQL tools below as an escape hatch for custom queries not covered above — sales history, aggregations, complex joins, or tables without a dedicated tool.

Resource: `artblocks://about`

Fetch this resource for platform context — vocabulary, verticals, chains, tags, user profiles, and a guide to which tool handles what.

Tool Hierarchy

Use tools in this order — skip steps you don't need:

1. Discover schema → explore_table (single table with fields + relationships) or graphql_introspection (full schema)
Build a validated query → build_query (validates fields, adds suggestions, auto-filters by chain)
Optimize → query_optimizer (rewrites to preferred tables, e.g. projects_metadata over projects)
Execute → INLINECODE16

If you already know the schema, go straight to build_query → graphql_query.

Tool: `explore_table`

For well-known tables (projects_metadata, tokens_metadata), returns a curated shortlist of the most useful fields organized by category (Identity, Status, Media, Market, etc.) plus key relationships with suggested subfields. Pass showAllFields: true to see the full schema dump instead.

Param	Required	Notes
INLINECODE23	yes	Table to explore
INLINECODE24

— | true for full schema dump (default: curated shortlist)|

Preferred Tables

Always use the _metadata variants — they include richer joined data:

Use this	Not this
INLINECODE27	INLINECODE28
INLINECODE29

tokens |
| contracts_metadata | contracts |

INLINECODE33 will automatically rewrite queries that use the wrong table.

Chain IDs

Chain	ID
Ethereum mainnet	INLINECODE34 (default)
Arbitrum

42161 | | Base | 8453 |

Pass chainId to graphql_query to make $chainId available as a variable in your query.

Common Query Patterns

These examples show queries that require raw GraphQL — things the domain tools can't do.

Recent sales (no domain tool covers purchases)

CODEBLOCK0

Aggregate token count by owner for a project

CODEBLOCK1

All tokens for a project (domain tools only return per-wallet)

CODEBLOCK2

Projects with specific on-chain attributes

CODEBLOCK3

Tips

- Use explore_table to understand fields and relationships before writing a query — the curated view is much easier to scan than the full schema dump
INLINECODE41 is the safest way to start — it validates fields and tells you what's available
Always pass chainId when querying multi-chain data to avoid cross-chain noise
For unknown fields, validate_fields is faster than a full introspection

查询 Art Blocks 数据

何时使用 GraphQL 与领域工具

领域特定工具覆盖了大多数用例，且更易于使用：

需求	工具
浏览/搜索项目	discoverprojects
完整项目详情

将以下 GraphQL 工具作为应急出口，用于上述工具未覆盖的自定义查询——如销售历史、聚合统计、复杂关联查询，或没有专用工具的数据表。

资源：artblocks://about

获取此资源以了解平台上下文——包括词汇表、垂直领域、链、标签、用户画像，以及各工具功能指南。

工具层级

按此顺序使用工具——可跳过不需要的步骤：

1. 发现模式 → exploretable（单表字段+关系）或 graphqlintrospection（完整模式）
构建验证查询 → buildquery（验证字段、添加建议、自动按链过滤）
优化 → queryoptimizer（重写为更优表，如用 projectsmetadata 替代 projects）
执行 → graphqlquery

如果已知模式结构，可直接使用 buildquery → graphqlquery。

工具：explore_table

对于已知表（projectsmetadata、tokensmetadata），返回按类别（身份、状态、媒体、市场等）组织的最常用字段精选列表，以及带建议子字段的关键关系。传入 showAllFields: true 可查看完整模式转储。

参数	必填	说明
tableName	是	要探索的表
showAllFields

— | true 显示完整模式转储（默认：精选列表）|

使用此表	非此表
projectsmetadata	projects
tokensmetadata

链 ID

链	ID
以太坊主网	1（默认）
Arbitrum

42161 | | Base | 8453 |

向 graphql_query 传入 chainId，使 $chainId 可作为查询中的变量使用。

常见查询模式

以下示例展示了需要原始 GraphQL 的查询——即领域工具无法实现的功能。

近期销售（无领域工具覆盖购买记录）

graphql query { purchases_metadata( orderby: { blocktimestamp: desc } limit: 20 where: { chainid: { eq: 1 } } ) { token_id priceineth block_timestamp buyer_address seller_address } }

按所有者统计项目代币数量

graphql query { tokensmetadataaggregate( where: { projectid: { eq: 0xa7d8d9ef8d8ce8992df33d8b8cf4aebabd5bd270-78 } } distincton: owneraddress ) { aggregate { count } } }

项目的所有代币（领域工具仅返回按钱包查询）

graphql query { tokens_metadata( where: { projectid: { eq: 0xa7d8d9ef8d8ce8992df33d8b8cf4aebabd5bd270-0 } } order_by: { invocation: asc } limit: 50 ) { token_id invocation owner_address features } }

具有特定链上属性的项目

graphql query { projects_metadata( where: { scripttypeandversion: { ilike: %three% } chainid: { eq: 1 } complete: { _eq: false } } limit: 20 ) { id name artist_name scripttypeand_version invocations max_invocations } }

提示

- 在编写查询前使用 exploretable 了解字段和关系——精选视图比完整模式转储更易浏览
buildquery 是最安全的起点——它验证字段并告知可用内容
查询多链数据时始终传入 chainId，以避免跨链干扰
对于未知字段，validate_fields 比完整内省查询更快

query-artblocks-data查询艺术区块数据

query-artblocks-data