FrankChen021 commented on code in PR #20183:
URL: https://github.com/apache/druid/pull/20183#discussion_r4359767021
##########
docs/querying/sql-metadata-tables.md:
##########
@@ -135,10 +135,61 @@ WHERE "IS_AGGREGATOR" = 'YES'
The "sys" schema provides visibility into Druid segments, servers and tasks.
:::info
- Note: "sys" tables do not currently support Druid-specific functions like
`TIME_PARSE` and
- `APPROX_QUANTILE_DS`. Only standard SQL functions can be used.
+ By default, "sys" tables use the SQL-layer execution path and support only
standard SQL functions. You can enable
+ experimental [native query execution](#native-query-execution) for supported
system tables, which enables expressions and
+ aggregations that the native SQL engine can translate.
+:::
+
+### Native query execution
+
+:::caution Experimental
+Native query execution for system tables is an experimental, opt-in feature.
Its behavior and interfaces may change.
:::
+The native SQL engine can plan supported system tables as native datasources.
To enable this behavior for a query, set
+`allowNativeFunctionsForSystemTables` to `true` in the SQL query context:
+
+```json
+{
+ "query": "SELECT COUNT(DISTINCT server) FROM sys.server_properties",
+ "context": {
+ "allowNativeFunctionsForSystemTables": true
+ }
+}
+```
+
+For clients that support setting query context parameters with SQL statements,
you can enable native system-table
+execution with `SET`:
+
+```sql
+SET allowNativeFunctionsForSystemTables = 'true';
+SELECT COUNT(DISTINCT server) FROM sys.server_properties;
+```
+
+Native system-table execution is available when the resolved SQL engine is
`native`. You don't need to explicitly set
+the `engine` context parameter when `native` is already the default engine.
The following tables support native query
+execution:
+
+|Table|Source of rows|
+|-----|--------------|
+|[`sys.server_properties`](#server_properties-table)|The Druid server
processes discovered in the cluster. Filters on `server` and `service_name` can
avoid reading properties from nodes that don't match.|
+
+After Druid retrieves the system-table rows, the native engine applies the
remaining filters, expressions,
+aggregations, sorting, and result processing. A system table that doesn't
advertise native query support continues to
+use its existing SQL-layer execution path, even when
`allowNativeFunctionsForSystemTables` is `true`.
+
+The parameter defaults to `false`. During a rolling upgrade, leave it disabled
until the Broker and all nodes
+that serve the native system tables have been upgraded. After the upgrade, you
can enable it by query or set
+`druid.query.default.context.allowNativeFunctionsForSystemTables=true` on
Brokers as the cluster-wide default. For more
+information, see [SQL query context](sql-query-context.md).
+
+Native system-table queries sent to the Router use distributed Broker
execution by default. To execute a native
+system-table Scan against only the contacted node, set the HTTP header
+`X-Druid-Native-Query-Route: local`. Local execution uses the authenticated
request identity and applies the table's
Review Comment:
For this header, it's set by broker, not by user. I think I should remove it
from the documentation. Exposing this internal technical details to users does
not make any sense.
User can also set this header, in this case, the query at router side is
treated as a query execution instead of proxying by using user's identity.
Broker fan out subqueries with this header and escalcated identity to nodes,
and each node uses the escalcated identity for authorization.
--
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]
