Skip to content

Commit bc14458

Browse files
kanchana-mongodbrychipman
kanchana-mongodb
and
rychipman
authored
DOCSP-14091 doc for new sql formatVersion (#118)
* DOCSP-14091 doc for new sql formatVersion * DOCSP-14091 updates for review feedback * Update source/reference/pipeline/sql.txt Co-authored-by: Ryan Chipman <[email protected]> * DOCPS-14091 updates for tech review feedback * Apply suggestions from code review Co-authored-by: Ryan Chipman <[email protected]> * DOCSP-14091 updates for feedback Co-authored-by: Ryan Chipman <[email protected]>
1 parent c36962a commit bc14458

File tree

1 file changed

+245
-94
lines changed

1 file changed

+245
-94
lines changed

‎source/reference/pipeline/sql.txt

Lines changed: 245 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ Syntax
2828
$sql: {
2929
statement: "<SQL-statement>",
3030
format: "jdbc",
31-
formatVersion: 1,
31+
formatVersion: <version-number>,
3232
dialect: "mysql"
3333
}
3434
}
@@ -59,8 +59,14 @@ Fields
5959

6060
* - ``formatVersion``
6161
- int
62-
- Version of the requested schema format. If omitted, defaults
63-
to the latest version of the requested schema format.
62+
- Version of the requested output format. {+adl+} supports the
63+
following versions for the jdbc output format:
64+
65+
- ``1``
66+
- ``2`` (latest)
67+
68+
If omitted, defaults to the latest version of the requested
69+
output format.
6470
- Optional
6571

6672
* - ``statement``
@@ -76,97 +82,242 @@ Output
7682
If the SQL statement is not a query or a command that returns a
7783
result set, the ``$sql`` stage does not return any documents.
7884

79-
If the SQL statement is a query, the ``$sql`` stage returns one document
80-
per row in the SQL result set. Each document includes a single array field
81-
named ``values`` that contains documents representing the columns in the
82-
result set and their values. For example:
83-
84-
.. code-block:: json
85-
:copyable: false
86-
87-
{
88-
"values": [
89-
{
90-
"database": "<databaseName>",
91-
"table": "<tableName>",
92-
"tableAlias": "<tableAlias>",
93-
"column": "<columnName>",
94-
"columnAlias": "<columnAlias>",
95-
"bsonType": "<bsonType>",
96-
"value": "<columnValue>"
97-
},
98-
...
99-
]
100-
}
101-
102-
.. list-table::
103-
:header-rows: 1
104-
:widths: 20 10 70
105-
106-
* - Field
107-
- Type
108-
- Description
109-
110-
* - ``database``
111-
- string
112-
- Name of the database. For queries against ``DUAL``, the field
113-
has a ``null`` value.
114-
115-
* - ``table``
116-
- string
117-
- Name of the table. For computed columns, the field has
118-
a ``null`` value.
119-
120-
* - ``tableAlias``
121-
- string
122-
- Alias for the table. If the query provides no alias, value is
123-
the same as the table name. For computed columns, the field has
124-
a ``null`` value.
125-
126-
* - ``column``
127-
- string
128-
- Name of the column. For computed columns, the field has
129-
a ``null`` value.
130-
131-
* - ``columnAlias``
132-
- string
133-
- Alias for the column. If the query provides no alias, value is
134-
the same as the column name. For computed columns, the field
135-
contains the column name.
136-
137-
* - ``bsonType``
138-
- string
139-
- The type of value. See :ref:`sql-bson-types` for more
140-
information.
141-
142-
* - ``value``
143-
- string
144-
- The column value.
145-
146-
If the result set of the query is empty, the output includes a
147-
field ``emptyResultSet`` whose value is ``true``. The ``values`` field
148-
has all of the column metadata, but the ``value`` field value is ``null``.
149-
For example:
150-
151-
.. code-block:: json
152-
:copyable: false
153-
:emphasize-lines: 2, 11
154-
155-
{
156-
"emptyResultSet": true,
157-
"values": [
158-
{
159-
"database": "<databaseName>",
160-
"table": "<tableName>",
161-
"tableAlias": "<tableAlias>",
162-
"column": "<columnName>",
163-
"columnAlias": "<columnAlias>",
164-
"bsonType": "<bsonType>",
165-
"value": "null"
166-
},
167-
...
168-
]
169-
}
85+
The output differs based on the format and format version used in the
86+
query.
87+
88+
.. tabs::
89+
90+
.. tab:: formatVersion 1
91+
:tabid: fv1
92+
93+
The ``value`` field value differs based on whether or not the
94+
result set is empty.
95+
96+
.. tabs::
97+
98+
.. tab:: Normal Result set
99+
:tabid: normal
100+
101+
If the SQL statement is a query, the ``$sql`` stage returns
102+
one document per row in the SQL result set. Each document
103+
includes a single array field named ``values`` that
104+
contains documents representing the columns in the result
105+
set and their values. For example:
106+
107+
.. code-block:: json
108+
:copyable: false
109+
110+
{
111+
"values": [
112+
{
113+
"database": "<databaseName>",
114+
"table": "<tableName>",
115+
"tableAlias": "<tableAlias>",
116+
"column": "<columnName>",
117+
"columnAlias": "<columnAlias>",
118+
"bsonType": "<bsonType>",
119+
"value": "<columnValue>"
120+
},
121+
...
122+
]
123+
}
124+
125+
.. tab:: Empty Result set
126+
:tabid: empty
127+
128+
If the result set of the query is empty, the output
129+
includes a field ``emptyResultSet`` whose value is
130+
``true``. The ``values`` field has all of the column
131+
metadata, but the ``value`` field value is ``null``. For
132+
example:
133+
134+
.. code-block:: json
135+
:copyable: false
136+
:emphasize-lines: 2, 11
137+
138+
{
139+
"emptyResultSet": true,
140+
"values": [
141+
{
142+
"database": "<databaseName>",
143+
"table": "<tableName>",
144+
"tableAlias": "<tableAlias>",
145+
"column": "<columnName>",
146+
"columnAlias": "<columnAlias>",
147+
"bsonType": "<bsonType>",
148+
"value": "null"
149+
},
150+
...
151+
]
152+
}
153+
154+
.. list-table::
155+
:header-rows: 1
156+
:widths: 20 10 70
157+
158+
* - Field
159+
- Type
160+
- Description
161+
162+
* - ``emptyResultSet``
163+
- boolean
164+
- Flag that indicates if the result set of the query is
165+
empty. Value is ``true`` if the result set of the query is
166+
empty. {+adl+} returns this field only if the result set
167+
of the query is empty.
168+
169+
* - ``values``
170+
- array of documents
171+
- Column metadata including column values.
172+
173+
* - ``values[n].database``
174+
- string
175+
- Name of the database. For queries against ``DUAL``, the
176+
field has a ``null`` value.
177+
178+
* - ``values[n].table``
179+
- string
180+
- Name of the table. For computed columns, the field has
181+
a ``null`` value.
182+
183+
* - ``values[n].tableAlias``
184+
- string
185+
- Alias for the table. If the query provides no alias, value
186+
is the same as the table name. For computed columns, the
187+
field has a ``null`` value.
188+
189+
* - ``values[n].column``
190+
- string
191+
- Name of the column. For computed columns, the field has
192+
a ``null`` value.
193+
194+
* - ``values[n].columnAlias``
195+
- string
196+
- Alias for the column. If the query provides no alias,
197+
value is the same as the column name. For computed
198+
columns, the field contains the column name.
199+
200+
* - ``values[n].bsonType``
201+
- string
202+
- Type of value. See :ref:`sql-bson-types` for more
203+
information.
204+
205+
* - ``values[n].value``
206+
- |bson| data type
207+
- Column value. Value is ``null`` if the result set of the
208+
query is empty.
209+
210+
.. tab:: formatVersion 2
211+
:tabid: fv2
212+
213+
The number of documents in the output differs based on whether or
214+
not the result set is empty.
215+
216+
.. tabs::
217+
218+
.. tab:: Normal Result set
219+
:tabid: normal
220+
221+
If the SQL statement is a query, the ``$sql`` stage returns
222+
the schema information in the first document. Subsequent
223+
documents, one per row in the SQL result set, include a
224+
single array field named ``values`` that contains only the
225+
values for the columns in the result set. For example:
226+
227+
.. code-block:: json
228+
:copyable: false
229+
230+
{
231+
"columns": [
232+
{
233+
"database": "<databaseName>",
234+
"table": "<tableName>",
235+
"tableAlias": "<tableAlias>",
236+
"column": "<columnName>",
237+
"columnAlias": "<columnAlias>",
238+
"bsonType": "<bsonType>"
239+
},
240+
...
241+
]
242+
}
243+
{ "values": [<columnValue>,...] }
244+
...
245+
246+
.. tab:: Empty Result set
247+
:tabid: empty
248+
249+
If the result set of the query is empty, the output
250+
includes only one document that contains the schema
251+
information. The documents that contain the values for the
252+
columns in the result set are not in the output. For
253+
example:
254+
255+
.. code-block:: json
256+
:copyable: false
257+
258+
{
259+
"columns": [
260+
{
261+
"database": "<databaseName>",
262+
"table": "<tableName>",
263+
"tableAlias": "<tableAlias>",
264+
"column": "<columnName>",
265+
"columnAlias": "<columnAlias>",
266+
"bsonType": "<bsonType>"
267+
},
268+
...
269+
]
270+
}
271+
272+
.. list-table::
273+
:header-rows: 1
274+
:widths: 20 10 70
275+
276+
* - Field
277+
- Type
278+
- Description
279+
280+
* - ``columns``
281+
- array of documents
282+
- Information on the columns.
283+
284+
* - ``columns[n].database``
285+
- string
286+
- Name of the database. For queries against ``DUAL``, the
287+
field has a ``null`` value.
288+
289+
* - ``columns[n].table``
290+
- string
291+
- Name of the table. For computed columns, the field has
292+
a ``null`` value.
293+
294+
* - ``columns[n].tableAlias``
295+
- string
296+
- Alias for the table. If the query provides no alias, value
297+
is the same as the table name. For computed columns, the
298+
field has a ``null`` value.
299+
300+
* - ``columns[n].column``
301+
- string
302+
- Name of the column. For computed columns, the field has
303+
a ``null`` value.
304+
305+
* - ``columns[n].columnAlias``
306+
- string
307+
- Alias for the column. If the query provides no alias,
308+
value is the same as the column name. For computed
309+
columns, the field contains the column name.
310+
311+
* - ``columns[n].bsonType``
312+
- string
313+
- Type of value. See :ref:`sql-bson-types` for more
314+
information.
315+
316+
* - ``values``
317+
- array of |bson| data type
318+
- Column values for a row in the result set. Each ``values``
319+
document corresponds to a column in the ``columns`` array.
320+
Absent if the result set of the query is empty.
170321

171322
.. _adl-sql-eg:
172323

0 commit comments

Comments
 (0)