Skip to content

Commit 4be682b

Browse files
pdabre12lga-zurich
pdabre12
authored and
lga-zurich
committed
[docs] Add native sidecar plugin documentation
1 parent b9c6ba8 commit 4be682b

File tree

2 files changed

+106
-0
lines changed

2 files changed

+106
-0
lines changed

‎presto-docs/src/main/sphinx/plugin.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,5 @@ This chapter outlines the plugins in Presto that are available for various use c
88
:maxdepth: 1
99

1010
plugin/redis-hbo-provider
11+
plugin/native-sidecar-plugin
1112

‎presto-docs/src/main/sphinx/plugin/native-sidecar-plugin.rst‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
==============
2+
Native Sidecar
3+
==============
4+
5+
Use the native sidecar plugin in a native cluster to extend the capabilities of the cluster by allowing the underlying execution engine to be the source of truth.
6+
All supported functions, types and session properties are retrieved directly from the sidecar - a specialized worker node equipped with enhanced capabilities.
7+
Only features supported by the native execution engine are exposed during function resolution, resolving session properties and the types supported.
8+
9+
The native sidecar plugin also provides a native plan checker that validates compatibility between Presto and the native execution engine
10+
by sending Presto plan fragments to a sidecar endpoint `v1/velox/plan`, where they are translated into Velox compatible plan fragments.
11+
If any incompatibilities or errors are detected during the translation, they are surfaced immediately, allowing Presto to fail fast before allocating resources or scheduling execution.
12+
13+
To use the sidecar functionalities, at least one sidecar worker must be present in the cluster. The system supports flexible configurations: a mixed setup with both sidecar
14+
and regular C++ workers, or a cluster composed entirely of sidecar workers. A worker can be configured as a sidecar by adding the properties listed in :ref:`sidecar-worker-properties` section.
15+
16+
Configuration
17+
-------------
18+
19+
Coordinator properties
20+
^^^^^^^^^^^^^^^^^^^^^^
21+
To enable sidecar support on the coordinator, add the following properties to your coordinator configuration:
22+
23+
============================================ ===================================================================== ==============================
24+
Property Name Description Value
25+
============================================ ===================================================================== ==============================
26+
``coordinator-sidecar-enabled`` Enables sidecar in the coordinator true
27+
``native-execution-enabled`` Enables native execution true
28+
``presto.default-namespace`` Sets the default function namespace `native.default`
29+
============================================ ===================================================================== ==============================
30+
31+
.. _sidecar-worker-properties:
32+
Sidecar worker properties
33+
^^^^^^^^^^^^^^^^^^^^^^^^^
34+
Enable sidecar functionality with:
35+
36+
============================================ ===================================================================== ==============================
37+
Property Name Description Value
38+
============================================ ===================================================================== ==============================
39+
``native-sidecar`` Enables a sidecar worker true
40+
``presto.default-namespace`` Sets the default function namespace `native.default`
41+
============================================ ===================================================================== ==============================
42+
43+
Regular worker properties
44+
^^^^^^^^^^^^^^^^^^^^^^^^^
45+
For regular workers (not acting as sidecars), configure:
46+
47+
============================================ ===================================================================== ==============================
48+
Property Name Description Value
49+
============================================ ===================================================================== ==============================
50+
``presto.default-namespace`` Sets the default function namespace `native.default`
51+
============================================ ===================================================================== ==============================
52+
53+
The Native Sidecar plugin is designed to run with all its components enabled. Individual configuration properties must be specified in conjunction with one another to ensure the plugin operates as intended.
54+
While the Native Sidecar plugin allows modular configuration, the recommended usage is to enable all the components for full functionality.
55+
56+
Function registry
57+
-----------------
58+
59+
These properties must be configured in ``etc/function-namespace/native.properties`` to use the function namespace manager from the ``NativeSidecarPlugin``.
60+
61+
============================================ ===================================================================== ==============================
62+
Property Name Description Value
63+
============================================ ===================================================================== ==============================
64+
``function-namespace-manager.name`` Identifier used to register the function namespace manager `native`
65+
``function-implementation-type`` Indicates the language in which functions in this namespace CPP
66+
are implemented.
67+
``supported-function-languages`` Languages supported by the namespace manager. CPP
68+
============================================ ===================================================================== ==============================
69+
70+
Session properties
71+
-----------------
72+
73+
These properties must be configured in ``etc/session-property-providers/native-worker.properties`` to use the session property provider of the ``NativeSidecarPlugin``.
74+
75+
============================================ ===================================================================== ==============================
76+
Property Name Description Value
77+
============================================ ===================================================================== ==============================
78+
``session-property-provider.name`` Identifier for the session property provider backed by the sidecar. `native-worker`
79+
Enables discovery of supported session properties in native engine.
80+
============================================ ===================================================================== ==============================
81+
82+
Type Manager
83+
-----------------
84+
85+
These properties must be configured in ``etc/type-managers/native.properties`` to use the type manager of the ``NativeSidecarPlugin``.
86+
87+
============================================ ===================================================================== ==============================
88+
Property Name Description Value
89+
============================================ ===================================================================== ==============================
90+
``type-manager.name`` Identifier for the type manager. Registers types `native`
91+
supported by the native engine.
92+
============================================ ===================================================================== ==============================
93+
94+
Plan checker
95+
-----------------
96+
97+
These properties must be configured in ``etc/plan-checker-providers/native.properties`` to use the native plan checker of the ``NativeSidecarPlugin``.
98+
99+
============================================ ===================================================================== ==============================
100+
Property Name Description Value
101+
============================================ ===================================================================== ==============================
102+
``plan-checker-provider.name`` Identifier for the plan checker. Enables validation of Presto `native`
103+
query plans against native engine, ensuring execution compatibility.
104+
============================================ ===================================================================== ==============================
105+

0 commit comments

Comments
 (0)