Skip to main content

The postgraphile.tags.json5 file

You can load TagsFilePlugin as part of your configuration to have PostGraphile read a postgraphile.tags.json5 file from the current directory and process the tags and descriptions therein.

在配置中加载 TagsFilePlugin 后,PostGraphile 会自动读取当前目录下的 postgraphile.tags.json5 文件,并解析应用其中的 smart tag 与说明描述。

graphile.config.mjs
import { TagsFilePlugin } from "postgraphile/utils";

export default {
// ...
plugins: [TagsFilePlugin],
};

Merging/Overriding合并与覆盖​

If you provide a description for an entity in postgraphile.tags.json5 then that description will override any previous descriptions.

如果在 postgraphile.tags.json5 中为某个实体提供了描述,该描述将覆盖此前已有的描述。

If you provide tags for an entity in postgraphile.tags.json5, those tags will be merged with previous tags overriding tags with the same names but retaining other tags.

如果在 postgraphile.tags.json5 中为某个实体配置了 tag,这些 tag 会与原有 tag 进行合并:同名 tag 会被覆盖,其余 tag 则保留不变。

File format文件格式​

The file is in JSON5 (you can just use regular JSON if you prefer, but the extension must be .json5) and is formatted like this:

该文件采用 JSON5 格式(如果你更习惯标准 JSON 写法也可以,但文件扩展名必须为 .json5),其结构如下所示:

{
version: 1,
config: {
/*
* There can be entries here for:
*
* - `class`: for tables, composite types, views and materialized views
* - `attribute`: for columns/attributes (of any 'class' type)
* - `constraint`: for table constraints
* - `procedure`: for functions/procedures
*/
class: {
/*
* The next level describes the named type. We've just used the table
* name `"post"` but it could be `"my_schema.post"` if you have multiple
* tables with the same name and you don't want this rule to apply to
* all of them.
*/
post: {
/*
* This will override the description sourced from the PostgreSQL COMMENT.
*/
description: "A post within our forum.",

/*
* Add tags specific to the 'post' table here. You can omit this if you
* don't want to add any tags.
*/
tags: {
foreignKey: [
"(default_user_id) references user (id)|@fieldName defaultUser",
"(organization_id) references organization (id)|@fieldName organization",
],
},

/*
* We've added a shortcut to class-types so you can tag/describe
* columns at the same time of the class.
*/
attribute: {
/*
* Assuming `body` is one of the columns in the 'post' table.
*/
body: {
/*
* Optional description, if provided overrides the PostgreSQL
* `COMMENT ON COLUMN post.body`.
*/
description: "The body of the post",
tags: {
/*
* Here we indicate that the 'body' field will not be available
* in the update mutation.
*/
omit: "update",
},
},
},
},
},
},
}

Reading from an alternative path从自定义路径读取​

If you want to store your tags in a different file (e.g. postgraphile.tags.json to support a wider range of parsers) then you can use a custom plugin instead:

如果想把 tag 存放在其他路径或文件格式中(例如使用 postgraphile.tags.json 以兼容更多解析器),可以改用自定义插件:

graphile.config.mjs
import { pgSmartTagsFromFile } from "postgraphile/utils";

export default {
// ...
plugins: [
pgSmartTagsFromFile(
// JSON and JSONC are also JSON5 compatible, so you can use these extensions if you prefer:
"/path/to/my/tags.file.json",
),
],
};

If you're trying to avoid the fs module (e.g. because you're using webpack) then building and loading a basic smart tags plugin that doesn't read from the file system might look something like this:

如果你需要避免引入 fs 模块(例如在使用 webpack 打包时),可以像下面这样构建并加载一个不读取文件系统的基础 smart tags 插件:

graphile.config.mjs
import { jsonPgSmartTags } from "postgraphile/utils";

const MySmartTagsPlugin = jsonPgSmartTags({
version: 1,
config: {
class: {
post: {
tags: {
omit: "update",
},
},
},
},
});

export default {
// ...
plugins: [MySmartTagsPlugin],
};

Going further延伸阅读​

For greater flexibility, you might choose to check out pgSmartTags.

若需更强的灵活性,可以查阅 pgSmartTags。