Skip to main content

Refs引用(Refs)

When you have two database tables with a foreign key constraint between them, PostGraphile will automatically add that relation to your GraphQL schema in both directions. Sometimes you want to add additional links between types, perhaps links that traverse multiple relationships (e.g. post -> topic -> forum), or links that perform polymorphism over relations. For this need, we have refs. Refs are uni-directional (they do not automatically create a reverse field) and may be plural or singular. Plural refs support both list and connection interfaces in GraphQL.

当两张数据库表之间存在外键约束时,PostGraphile 会自动将这条 relation 以双向关联的形式添加到你的 GraphQL schema 中。但有时你可能希望在类型之间额外添加关联——比如跨越多个关系的路径(如 post -> topic -> forum),或跨关系的多态关联。针对这类需求,PostGraphile 提供了 ref。ref 是单向的(不会自动生成反向字段),既可以是复数也可以是单数。复数 ref 在 GraphQL 中同时支持列表和 Connection 接口。

note注意

Refs follow relations defined via foreign key constraints (or @foreignKey smart tags), attempts to build relations via a @ref without having an underlying foreign key relation will be ignored, though you may see a warning in the console such as:

ref 会沿着通过外键约束(或 @foreignKey smart tag)定义的 relation 进行跳转;如果底层没有对应的外键 relation,仅靠 @ref 构建关联的尝试将会被忽略,不过控制台可能会输出类似下面的警告:

When processing ref for resource 'posts', could not find matching relation for
via:'(author_id)->users'

@ref and @refVia@ref 与 @refVia​

The easiest way to define a ref is with a @ref smart tag. The first argument to your @ref smart tag is the name for your reference, and then it supports the following optional parameters:

定义 ref 最简单的方式是使用 @ref smart tag。@ref smart tag 的第一个参数是该引用的名称,随后支持以下可选参数:

  • to: - the name of the GraphQL type we're referencing (required if via: is not present)

    to: —— 所引用的 GraphQL 类型名称(当未指定 via: 时必填)

  • from: - the name of the GraphQL type we're applying the reference to when using polymorphism

    from: —— 使用多态时,应用该引用的 GraphQL 类型名称

  • via:- the route string (see below) through which we can reach the target

    via: —— 用于到达目标的路径字符串(详见下文)

  • singular - present if this is a singular relationship

    singular —— 表示这是一个单数关系

  • plural - indicates that the ref is plural (default). Not allowed if singular is specified.

    plural —— 表示该 ref 为复数关系(默认值)。如果已指定 singular,则不允许再使用该参数。

For example:

例如:

comment on table posts is $$
@ref author via:(author_id)->people(id) singular
$$;`

Sometimes we want a ref to use multiple routes; this might be because there's multiple join tables we want to traverse to the same target table, or because we want to target multiple tables. When we need this, instead of specifying a via: directly on the @ref smart tag, we add multiple @refVia smart tags, each with the ref name followed by a via: (see "Route strings" below):

有时我们希望一个 ref 可以走多条路径——可能是因为需要穿过多个连接表(join table)才能到达同一张目标表,也可能是因为需要指向多张不同的表。遇到这种情况时,无需直接在 @ref smart tag 上指定 via:,而是添加多个 @refVia smart tag,每个标签均以 ref 名称开头,后接 via:(见下文“路径字符串”):

comment on table books is $$
@ref relatedPeople to:Person
@refVia relatedPeople via:book_authors;people
@refVia relatedPeople via:book_editors;people
$$;

We can also use multiple targets to indicate polymorphism (see the polymorphism docs for full details):

我们也可以通过指向多个目标来表达多态关联(完整细节请参阅多态文档):

comment on table log_entries is $$
@ref author to:PersonOrOrganization singular
@refVia author via:(person_id)->people(person_id)
@refVia author via:(organization_id)->organizations(organization_id)
$$;

Route strings路径字符串(Route strings)​

The value for a via: parameter takes the form of a chain of one or more relationships separated by semicolons. Each relationship is either:

via: 参数的值由一个或多个以分号分隔的关系链组成。其中每一段关系可以是以下形式之一:

  • <table_name> - a table name (in which case there must be exactly one foreign key referencing this table), or

    <table_name> —— 表名(此时必须有且仅有一个外键引用该表),或

  • (<column>,...)-><table_name> - a list of local columns referencing a remote table's primary key

    (<column>,...)-><table_name> —— 一组引用目标表主键的本地列

  • (<column>,...)-><table_name>(<column>,...) - a list of local columns referencing a remote table's list of columns

    (<column>,...)-><table_name>(<column>,...) —— 一组引用目标表指定列的本地列