mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-15 09:22:43 +03:00
docs: restructure naming conventions page
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/4670 Co-authored-by: paritosh-08 <85472423+paritosh-08@users.noreply.github.com> GitOrigin-RevId: 848295d1dae95c618aac37da8df520412b08a677
This commit is contained in:
Rikin Kachhia
hasura-bot
parent
e4fc6a868e
commit
d328d673ca
@ -1,6 +1,6 @@
|
||||
---
|
||||
sidebar_label: Naming Convention
|
||||
sidebar_position: 13
|
||||
sidebar_label: Naming conventions
|
||||
sidebar_position: 9.5
|
||||
description: Customizing auto generated names in Hasura with a naming convention
|
||||
keywords:
|
||||
- hasura
|
||||
@ -16,7 +16,7 @@ import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
import GraphiQLIDE from '@site/src/components/GraphiQLIDE';
|
||||
|
||||
# Postgres: Naming Conventions
|
||||
# Postgres: Naming conventions
|
||||
|
||||
## Introduction
|
||||
|
||||
@ -25,7 +25,7 @@ convention for these autogenerated names can be customised to suit your needs.
|
||||
|
||||
:::tip Note
|
||||
|
||||
Naming Convention is an experimental feature and can be enabled by adding `naming-convention` to the
|
||||
Naming conventions are an experimental feature and can be enabled by adding `naming-convention` to the
|
||||
`HASURA_GRAPHQL_EXPERIMENTAL_FEATURES` environment variable array or with the server flag `--experimental-feature`.
|
||||
|
||||
:::
|
||||
@ -33,22 +33,23 @@ Naming Convention is an experimental feature and can be enabled by adding `namin
|
||||
|
||||
:::note Supported from
|
||||
|
||||
Naming Convention is available at version `v2.8.0` and higher.
|
||||
Naming conventions are available at version `v2.8.0` and higher.
|
||||
|
||||
:::
|
||||
|
||||
:::info Database Support
|
||||
|
||||
Naming Convention is only available on Postgres sources
|
||||
Naming conventions are only available on Postgres sources
|
||||
|
||||
:::
|
||||
|
||||
## Supported naming conventions
|
||||
|
||||
Currently, Hasura provides two naming conventions:
|
||||
|
||||
- `hasura-default`: This is the **default** naming convention used in the Hasura Server and is used when a naming
|
||||
- `hasura-default`: This is the **default** naming convention used in the Hasura server and is used when a naming
|
||||
convention is not explicitly specified. In this naming convention, all names will use snake casing (`snake_case`) and
|
||||
defined enum table values will not change. This is the only naming convention available prior to `v2.8.0`.
|
||||
defined enum table values will not change.
|
||||
|
||||
- `graphql-default`: This is a new naming convention which is more popular in the Javascript ecosystem.
|
||||
Suppose you have a table called `my_table` in schema `my_schema`, this convention will work as follows:
|
||||
@ -66,105 +67,169 @@ Suppose you have a table called `my_table` in schema `my_schema`, this conventio
|
||||
| `hasura-default` | Snake case | Snake case | Snake case | as defined |
|
||||
| `graphql-default` | Camel case | Pascal case | Camel case | Uppercased |
|
||||
|
||||
## How to set a naming convention?
|
||||
|
||||
To set a naming convention in Hasura Server, you can do the following:
|
||||
:::tip Note
|
||||
|
||||
### Set default naming convention for all sources
|
||||
- Setting [custom table and field names](/graphql/core/databases/postgres/schema/custom-field-names.mdx)
|
||||
in Hasura will override the naming convention of the source. For example, if the custom table name is set to
|
||||
`my_table` and `naming_convention` is `graphql-default`, the field names generated will be `my_table`,
|
||||
`my_tableByPk`, `my_tableAggregate` and so on.
|
||||
- `hasura-default` is the naming convention used prior to `v2.8.0`.
|
||||
|
||||
For setting the default naming convention for all sources, set the environment variable
|
||||
`HASURA_GRAPHQL_DEFAULT_NAMING_CONVENTION` to one of `hasura-default` or `graphql-default`. This means any database
|
||||
source will follow this naming convention unless explicitly set to something else.
|
||||
:::
|
||||
|
||||
### Set naming convention for a particular source
|
||||
**For example:**
|
||||
|
||||
To set the naming convention of a particular source, you can set the `naming_convention` field in the
|
||||
[source customization](/graphql/core/api-reference/syntax-defs.mdx#sourcecustomization) field of the metadata.
|
||||
Setting the convention in the source customization will override the default naming convention.
|
||||
|
||||
## Example
|
||||
|
||||
Consider a schema named, `app_db`, with the following two tables:
|
||||
Consider a schema named, `app_db`, with the following structure:
|
||||
|
||||
1. **app_users**: A table with the columns **user_id**, **username**, **last_seen**, **favourite_day** and
|
||||
**referred_by**.
|
||||
2. **week_days**: An enum table with column **day_names** and rows **monday**, **tuesday** and so on.
|
||||
3. We have a foreign key set up between `week_days.day_names` and `app_users.favourite_day`.
|
||||
|
||||
Note that we have a foreign key setup between `week_days.day_names` and `app_users.favourite_day`.
|
||||
For the above schema, a sample GraphQL query will look like the following with the different naming conventions:
|
||||
|
||||
For the above setup, an example graphql query looks like the following:
|
||||
**hasura-default**
|
||||
|
||||
<GraphiQLIDE
|
||||
query={`query get_user_aggregate {
|
||||
app_db_app_users_aggregate(
|
||||
distinct_on: referred_by,
|
||||
where: {favourite_day: {_eq: sunday}}
|
||||
) {
|
||||
aggregate {
|
||||
count
|
||||
stddev_pop {
|
||||
user_id
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
`}
|
||||
response={`{
|
||||
"data": {
|
||||
"app_db_app_users_aggregate": {
|
||||
"aggregate": {
|
||||
"count": 0,
|
||||
"stddev_pop": {
|
||||
"user_id": null
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
`}
|
||||
/>
|
||||
|
||||
**graphql-default**
|
||||
|
||||
<GraphiQLIDE
|
||||
query={`query get_user_aggregate {
|
||||
appDbAppUsersAggregate(
|
||||
distinctOn: referredBy,
|
||||
where: {favouriteDay: {_eq: SUNDAY}}
|
||||
) {
|
||||
aggregate {
|
||||
count
|
||||
stddevPop {
|
||||
userId
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
`}
|
||||
response={`{
|
||||
"data": {
|
||||
"appDbAppUsersAggregate": {
|
||||
"aggregate": {
|
||||
"count": 0,
|
||||
"stddevPop": {
|
||||
"userId": null
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
`}
|
||||
/>
|
||||
|
||||
## Set default naming convention for all sources {#pg-default-naming-convention}
|
||||
|
||||
For setting the default naming convention for all sources, set the environment variable
|
||||
`HASURA_GRAPHQL_DEFAULT_NAMING_CONVENTION` to one of `hasura-default` or `graphql-default`.
|
||||
|
||||
This means any database source will follow this naming convention unless explicitly set to something else.
|
||||
|
||||
## Set naming convention for a particular source {#pg-source-naming-convention}
|
||||
|
||||
<Tabs className="api-tabs">
|
||||
<TabItem value="console" label="Console">
|
||||
|
||||
Console support will be added soon.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="cli" label="CLI">
|
||||
|
||||
Head to the
|
||||
`/metadata/databases/databases.yaml` file and add the database
|
||||
configuration as below:
|
||||
|
||||
```yaml {6-7}
|
||||
- name: <db_name>
|
||||
configuration:
|
||||
connection_info:
|
||||
database_url:
|
||||
from_env: <DB_URL_ENV_VAR>
|
||||
customization:
|
||||
naming_convention: hasura-default
|
||||
tables: []
|
||||
functions: []
|
||||
```
|
||||
|
||||
Apply the metadata by running:
|
||||
|
||||
```bash
|
||||
hasura metadata apply
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="api" label="API">
|
||||
|
||||
You can set the naming convention of a particular source using the `customization` field in the
|
||||
[pg_add_source](/graphql/core/api-reference/metadata-api/source.mdx#metadata-pg-add-source) metadata API.
|
||||
|
||||
```http {16-18}
|
||||
POST /v1/metadata HTTP/1.1
|
||||
Content-Type: application/json
|
||||
X-Hasura-Role: admin
|
||||
|
||||
<TabItem value="hasura" label="hasura-default">
|
||||
<GraphiQLIDE
|
||||
query={`
|
||||
query MyQuery {
|
||||
app_db_app_users_aggregate(distinct_on: referred_by, where: {favourite_day: {_eq: sunday}}) {
|
||||
aggregate {
|
||||
count
|
||||
stddev_pop {
|
||||
user_id
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
`}
|
||||
response={`
|
||||
{
|
||||
"data": {
|
||||
"app_db_app_users_aggregate": {
|
||||
"aggregate": {
|
||||
"count": 0,
|
||||
"stddev_pop": {
|
||||
"user_id": null
|
||||
"type": "pg_add_source",
|
||||
"args": {
|
||||
"name": "<db_name>",
|
||||
"configuration": {
|
||||
"connection_info": {
|
||||
"database_url": {
|
||||
"from_env": "<DB_URL_ENV_VAR>"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"customization": {
|
||||
"naming_convention": "hasura-default"
|
||||
},
|
||||
"replace_configuration": true
|
||||
}
|
||||
}
|
||||
`}
|
||||
/>
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="graphql" label="graphql-default">
|
||||
<GraphiQLIDE
|
||||
query={`
|
||||
query MyQuery {
|
||||
appDbAppUsersAggregate(distinctOn: referredBy, where: {favouriteDay: {_eq: SUNDAY}}) {
|
||||
aggregate {
|
||||
count
|
||||
stddevPop {
|
||||
userId
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
`}
|
||||
response={`
|
||||
{
|
||||
"data": {
|
||||
"appDbAppUsersAggregate": {
|
||||
"aggregate": {
|
||||
"count": 0,
|
||||
"stddevPop": {
|
||||
"userId": null
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
`}
|
||||
/>
|
||||
</TabItem>
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
:::tip Note
|
||||
|
||||
Note that setting custom table names and [custom field names](/graphql/core/databases/postgres/schema/custom-field-names.mdx)
|
||||
in Hasura will override the naming convention of the source. For example, if the custom table name is set to
|
||||
`my_table` and `naming_convention` is `graphql-default`, the field names generated will be `my_table`,
|
||||
`my_tableByPk`, `my_tableAggregate` and so on.
|
||||
Setting the convention in the source customization will override the default naming convention.
|
||||
|
||||
:::
|
||||
|
||||
|
||||
|
||||
|
||||
@ -856,6 +856,26 @@ Used to set the connection initialisation timeout for
|
||||
|
||||
(default: `3`)
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
N/A
|
||||
</td>
|
||||
<td>
|
||||
|
||||
`HASURA_GRAPHQL_DEFAULT_NAMING_CONVENTION`
|
||||
|
||||
</td>
|
||||
<td>
|
||||
|
||||
Used to set the default naming convention for all sources. See
|
||||
[naming convention](/graphql/core/databases/postgres/schema/naming-convention.mdx) for more information.
|
||||
|
||||
(default: `hasura-default`)
|
||||
|
||||
<em>(Available for versions ≥ v2.8.0)</em>
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user