Skip to content

Commit 42916ad

Browse files
plcplchasura-bot
plcplc
authored and
hasura-bot
committed
docs: Port Postgres docs of Native Queries and Logical Models to other supported backends
PR-URL: hasura/graphql-engine-mono#9483 GitOrigin-RevId: e2e52c14cdde2eabb7f23b5d4991fd467609b313
1 parent 89ca064 commit 42916ad

File tree

7 files changed

+549
-31
lines changed

7 files changed

+549
-31
lines changed

‎docs/docs/api-reference/metadata-api/logical-models.mdx

+6-3
Original file line numberDiff line numberDiff line change
@@ -181,7 +181,9 @@ X-Hasura-Role: admin
181181
}
182182
```
183183

184-
The type of each field can be any valid SQL Server data type, and each field can be marked as nullable or not.
184+
The type of each field can be either a SQL Server data type
185+
or references to other Logical Models, and each field can be marked as nullable or not, see
186+
[LogicalModelType](/api-reference/syntax-defs.mdx#logicalmodeltype).
185187

186188
### Args syntax {#metadata-mssql-track-logical-model-syntax}
187189

@@ -308,8 +310,9 @@ X-Hasura-Role: admin
308310
}
309311
```
310312

311-
The type of each field can be any valid [BigQuery data type](/schema/bigquery/bigquery-types.mdx), and each field can be
312-
marked as nullable or not.
313+
The type of each field can be either a [BigQuery data type](/schema/bigquery/bigquery-types.mdx)
314+
or references to other Logical Models, and each field can be marked as nullable or not, see
315+
[LogicalModelType](/api-reference/syntax-defs.mdx#logicalmodeltype).
313316

314317
### Args syntax {#metadata-bigquery-track-logical-model-syntax}
315318

‎docs/docs/api-reference/metadata-api/native-queries.mdx

+4
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,8 @@ X-Hasura-Role: admin
119119
"description": "<optional field description>"
120120
}
121121
},
122+
"array_relationships": <Native Query relationship>,
123+
"object_relationshps": <Native Query relationship>,
122124
"code": "<SQL query>",
123125
"returns": "<logical model name>"
124126
}
@@ -185,6 +187,8 @@ X-Hasura-Role: admin
185187
"description": "<optional field description>"
186188
}
187189
},
190+
"array_relationships": <Native Query relationship>,
191+
"object_relationshps": <Native Query relationship>,
188192
"code": "<SQL query>",
189193
"returns": "<logical model name>"
190194
}

‎docs/docs/schema/bigquery/logical-models/index.mdx

+130-14
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ import ProductBadge from '@site/src/components/ProductBadge';
2222

2323
:::tip Supported from
2424

25-
Native queries are supported from `v2.26.0`.
25+
Logical Models are supported from `v2.26.0`.
2626

2727
:::
2828

@@ -62,7 +62,7 @@ X-Hasura-Role: admin
6262
"fields": [
6363
{
6464
"name": "<field name>",
65-
"type": "<BigQuery field type>",
65+
"type": "<BigQuery Logical Model type>",
6666
"nullable": false | true,
6767
"description": "<optional field description>"
6868
},
@@ -75,8 +75,9 @@ X-Hasura-Role: admin
7575
</TabItem>
7676
</Tabs>
7777

78-
The type of each field can be any valid [BigQuery data type](/schema/bigquery/bigquery-types.mdx), and each field can be
79-
marked as nullable or not.
78+
The type of each field can be either a [BigQuery data type](/schema/bigquery/bigquery-types.mdx)
79+
or references to other Logical Models, and each field can be marked as nullable or not, see
80+
[LogicalModelType](/api-reference/syntax-defs.mdx#logicalmodeltype).
8081

8182
For example, we could track a representation of an article as follows:
8283

@@ -96,24 +97,39 @@ X-Hasura-Role: admin
9697
"fields": [
9798
{
9899
"name": "id",
99-
"type": "integer"
100+
"type":
101+
{
102+
"scalar": "integer"
103+
}
100104
},
101105
{
102106
"name": "title",
103-
"type": "text"
107+
"type":
108+
{
109+
"scalar": "text"
110+
}
104111
},
105112
{
106113
"name": "contents",
107-
"type": "text"
114+
"type":
115+
{
116+
"scalar": "text"
117+
}
108118
},
109119
{
110120
"name": "published_date",
111-
"type": "published_date",
112-
"nullable": true
121+
"type":
122+
{
123+
"scalar": "date",
124+
"nullable": true
125+
},
113126
},
114127
{
115128
"name": "is_published",
116-
"type": "boolean"
129+
"type":
130+
{
131+
"scalar": "boolean"
132+
}
117133
}
118134
]
119135
}
@@ -176,6 +192,110 @@ X-Hasura-Role: admin
176192
</TabItem>
177193
</Tabs>
178194

195+
## Referencing other Logical Models {#referencing-other-logical-models}
196+
197+
Logical Model fields are allowed to refer to other Logical Models, even recursively, allowing nested data types.
198+
199+
Object or array relationships between Native Queries are an example use of this.
200+
201+
To elaborate on the "article" example above, we can include authors in the data model:
202+
203+
<Tabs groupId="user-preference" className="api-tabs">
204+
<TabItem value="api" label="API">
205+
206+
```http
207+
POST /v1/metadata HTTP/1.1
208+
Content-Type: application/json
209+
X-Hasura-Role: admin
210+
211+
{
212+
"type": "bulk",
213+
"args":
214+
[
215+
{
216+
"type": "bigquery_track_logical_model",
217+
"args": {
218+
"source": "default",
219+
"name": "article",
220+
"fields": [
221+
{
222+
"name": "id",
223+
"type":
224+
{
225+
"scalar": "integer"
226+
}
227+
},
228+
{
229+
"name": "title",
230+
"type":
231+
{
232+
"scalar": "text"
233+
}
234+
},
235+
{
236+
"name": "contents",
237+
"type":
238+
{
239+
"scalar": "text"
240+
}
241+
},
242+
{
243+
"name": "author_id",
244+
"type":
245+
{
246+
"scalar": "integer"
247+
}
248+
},
249+
{
250+
"name": "author",
251+
"type":
252+
{
253+
"logical_model": "author",
254+
},
255+
}
256+
]
257+
}
258+
},
259+
{
260+
"type": "bigquery_track_logical_model",
261+
"args": {
262+
"source": "default",
263+
"name": "author",
264+
"fields": [
265+
{
266+
"name": "id",
267+
"type":
268+
{
269+
"scalar": "integer"
270+
}
271+
},
272+
{
273+
"name": "name",
274+
"type":
275+
{
276+
"scalar": "text"
277+
}
278+
},
279+
{
280+
"name": "articles",
281+
"type":
282+
{
283+
"array":
284+
{
285+
"logical_model": "article"
286+
}
287+
}
288+
}
289+
]
290+
}
291+
}
292+
]
293+
}
294+
```
295+
296+
</TabItem>
297+
</Tabs>
298+
179299
## Permissions
180300

181301
By default, a model has no permissions, and only the admin account will be able to use it. You can enable the model by
@@ -278,7 +398,3 @@ X-Hasura-Role: admin
278398

279399
</TabItem>
280400
</Tabs>
281-
282-
## Relationships
283-
284-
Currently, Logical Models do not support relationships. They will be supported in a future release.

‎docs/docs/schema/bigquery/logical-models/native-queries.mdx

+139
Original file line numberDiff line numberDiff line change
@@ -275,6 +275,19 @@ X-Hasura-Role: admin
275275
"description": "<optional field description>"
276276
}
277277
},
278+
"array_relationships": [
279+
{
280+
"name": "<relationship name>",
281+
"using": {
282+
"column_mapping": {
283+
"<local column>": "<remote column>"
284+
},
285+
"remote_native_query: "<remote native query name>"
286+
}
287+
}
288+
],
289+
"object_relationships": <same as array_relationships>,
290+
"description": "<text>",
278291
"code": "<SQL query>",
279292
"returns": "<logical model name>"
280293
}
@@ -342,3 +355,129 @@ A future release will allow mutations to be specified using native queries.
342355
Native queries will inherit the permissions of the Logical Model that they return. See the
343356
[documentation on Logical Models](/schema/bigquery/logical-models/index.mdx) for an explanation of how to add
344357
permissions.
358+
359+
## Relationships
360+
361+
Relationships are supported between Native Queries.
362+
This is how Native Queries may implement object and array fields of their referenced Logical Model.
363+
364+
Unlike tables, relationships for a Native Query have to be given as part of
365+
tracking the Native Query: The schema of a Native Query is defined by its
366+
Logical Model, and the Native Query needs to implement all the fields of the
367+
Logical Model in order to be tracked successfully.
368+
369+
Currently relationships are only supported between Native Queries residing in the same source.
370+
371+
As an example, consider the following Native Queries which implement the data
372+
model of articles and authors given in the section on [Logical Model references](/schema/bigquery/logical-models/index.mdx#referencing-other-logical-models):
373+
374+
<Tabs groupId="user-preference" className="api-tabs">
375+
<TabItem value="api" label="API">
376+
377+
```http
378+
POST /v1/metadata HTTP/1.1
379+
Content-Type: application/json
380+
X-Hasura-Role: admin
381+
382+
{
383+
"type": "bulk_atomic",
384+
"args":
385+
[
386+
{ "args": {
387+
"arguments": {
388+
"length": {
389+
"nullable": false,
390+
"type": "integer"
391+
}
392+
},
393+
"array_relationships": [],
394+
"code": "
395+
SELECT
396+
id,
397+
title,
398+
(substring(content, 1, {{length}}) ||
399+
(CASE WHEN length(content) < {{length}}
400+
THEN '' ELSE '...' END))
401+
AS contents,
402+
date
403+
FROM article",
404+
"object_relationships": [
405+
{
406+
"name": "author",
407+
"using": {
408+
"column_mapping": {
409+
"author_id": "id"
410+
},
411+
"remote_native_query": "get_authors"
412+
}
413+
}
414+
],
415+
"returns": "article",
416+
"root_field_name": "get_articles",
417+
"source": "bigquery",
418+
"type": "query"
419+
},
420+
"type": "bigquery_track_native_query"
421+
},
422+
,{ "args": {
423+
"arguments": {},
424+
"array_relationships": [
425+
{
426+
"name": "articles",
427+
"using": {
428+
"column_mapping": {
429+
"id": "author_id"
430+
},
431+
"remote_native_query": "get_articles"
432+
}
433+
}
434+
],
435+
"code": "SELECT * FROM authors",
436+
"object_relationships": [],
437+
"returns": "author",
438+
"root_field_name": "get_authors",
439+
"source": "bigquery",
440+
"type": "query"
441+
},
442+
"type": "bigquery_track_native_query"
443+
}
444+
]
445+
}
446+
```
447+
448+
:::info Wrap calls in `bulk_atomic`
449+
450+
Similar to Logical Models, tracking the Native Queries one-by-one would fail,
451+
since `get_articles` refers to `get_authors`, which is not yet defined.
452+
453+
Tracking the Native Queries in one atomic operation postpones coherency checks
454+
until all models are tracked, which allows for mutual references.
455+
456+
:::
457+
458+
</TabItem>
459+
<TabItem value="query" label="Query">
460+
The Native Queries in this example enable queries like:
461+
462+
```graphql
463+
query {
464+
get_authors
465+
{
466+
name
467+
468+
short_excerpt: articles(args: {length: 10})
469+
{
470+
title
471+
contents
472+
}
473+
474+
long_excerpt: articles(args: {length: 100})
475+
{
476+
title
477+
contents
478+
}
479+
}
480+
}
481+
```
482+
</TabItem>
483+
</Tabs>

0 commit comments

Comments
 (0)