clintropolis commented on code in PR #12922:
URL: https://github.com/apache/druid/pull/12922#discussion_r949851621
##########
docs/querying/virtual-columns.md:
##########
@@ -80,4 +82,106 @@ The expression virtual column has the following syntax:
|--------|-----------|---------|
|name|The name of the virtual column.|yes|
|expression|An [expression](../misc/math-expr.md) that takes a row as input
and outputs a value for the virtual column.|yes|
-|outputType|The expression's output will be coerced to this type. Can be LONG,
FLOAT, DOUBLE, or STRING.|no, default is FLOAT|
+|outputType|The expression's output will be coerced to this type. Can be LONG,
FLOAT, DOUBLE, STRING, ARRAY types, or COMPLEX types.|no, default is FLOAT|
+
+
+### Nested field virtual column
+
+The nested field virtual column is an optimized virtual column that can
provide direct access into various paths of
+a `COMPLEX<json>` column, including using their indexes.
+
+Syntax (all 3 of these virtual columns produce the same output):
+```json
+ {
+ "type": "nested-field",
+ "columnName": "shipTo",
+ "outputName": "v0",
+ "expectedType": "STRING",
+ "path": "$.phoneNumbers[1].number"
+ }
+```
+```json
+ {
+ "type": "nested-field",
+ "columnName": "shipTo",
+ "outputName": "v1",
+ "expectedType": "STRING",
+ "path": ".phoneNumbers[1].number",
+ "useJqSyntax": true
+ }
+```
+
+```json
+ {
+ "type": "nested-field",
+ "columnName": "shipTo",
+ "outputName": "v2",
+ "expectedType": "STRING",
+ "pathParts": [
+ {
+ "type": "field",
+ "field": "phoneNumbers"
+ },
+ {
+ "type": "arrayElement",
+ "index": 1
+ },
+ {
+ "type": "field",
+ "field": "number"
+ }
+ ]
+ }
+```
+
+|property|description|required?|
+|--------|-----------|---------|
+|columnName|The name of the virtual column.|yes|
+|outputName|The name of the virtual column.|yes|
+|expectedType|The name of the virtual column.|yes|
+|pathParts|The name of the virtual column.|yes|
+|processFromRaw|If set to true, the virtual column will process the "raw" JSON
data to extract values rather than using an optimized "literal" value selector.
This option allows extracting non-literal values (such as nested JSON objects
or arrays) as a `COMPLEX<json>` at the cost of much slower performance.|No,
default false|
+|path|'JSONPath' or 'jq' syntax path. One of `path` or `pathParts` must be
set|no, if `pathParts` is defined|
+|useJqSyntax||no, default is false|
+
+#### Nested path part
+|property|description|required?|
+|--------|-----------|---------|
+|type|Must be 'field' or 'arrayElement'|yes|
+|field|The name of the 'field' in a 'field' `type` path part|yes, if `type` is
'field'|
+|index|The array element index if `type` is `arrayElement`|yes, if `type` is
'arrayElement'|
+
+This virtual column is used for the SQL operators `JSON_VALUE` (if
`processFromRaw` is set to false) or `JSON_QUERY`
+(if it is true), and accepts 'JSONPath' or 'jq' syntax string representations
of paths, or a parsed
+list of "path parts" in order to determine what should be selected from the
column.
+
+Type information for nested fields is absent at higher levels (it is contained
within the segment, but not to segment
+metadata queries or the SQL planner), so `expectedType` provides the context
for how something is being used, e.g. an
+aggregators default type or an explicit cast, or, if using the 'RETURNING'
syntax which explicitly specifies type.
Review Comment:
i removed this section and just expanded the information for `expectedType`
to indicate that druid coerces values to the specified type if it is supplied.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
