Skip to content

Commit c6e0dea

Browse files
pramodsatyaj-sund
pramodsatya
authored and
j-sund
committed
[native] Add sidecar and sidecar plugin documentation
1 parent e19fb9e commit c6e0dea

File tree

3 files changed

+124
-1
lines changed

3 files changed

+124
-1
lines changed

‎presto-docs/src/main/sphinx/develop/spi-overview.rst‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,3 +94,62 @@ configuration variable ``catalog.config-dir``. In order for Presto to pick up
9494
the new plugin, you must restart Presto.
9595

9696
Plugins must be installed on all nodes in the Presto cluster (coordinator and workers).
97+
98+
Coordinator Plugin
99+
------------------
100+
101+
The ``CoordinatorPlugin`` interface allows plugins to provide additional
102+
functionality for the Presto coordinator. Presto SPI defines different service
103+
provider factories and service providers that allow customization of session
104+
property providers, function namespace managers, type managers, expression
105+
optimizers, and plan checkers. The following service providers can be accessed
106+
via their respective provider factories.
107+
108+
+----------------------+----------------------------------------+---------------------------------+
109+
| Service | Provider Factory | Service Provider |
110+
+======================+========================================+=================================+
111+
| Session Properties | WorkerSessionPropertyProviderFactory | WorkerSessionPropertyProvider |
112+
+----------------------+----------------------------------------+---------------------------------+
113+
| Functions | FunctionNamespaceManagerFactory | FunctionNamespaceManager |
114+
+----------------------+----------------------------------------+---------------------------------+
115+
| Types | TypeManagerFactory | TypeManager |
116+
+----------------------+----------------------------------------+---------------------------------+
117+
| Expression Optimizer | ExpressionOptimizerFactory | ExpressionOptimizer |
118+
+----------------------+----------------------------------------+---------------------------------+
119+
| Plan Checker | PlanCheckerProviderFactory | PlanCheckerProvider |
120+
+----------------------+----------------------------------------+---------------------------------+
121+
122+
``CoordinatorPlugin`` interface provides methods to access all registered
123+
provider factories that customize these services. In a Presto C++ cluster,
124+
the class ``NativeSidecarPlugin`` implements ``CoordinatorPlugin`` interface
125+
to customize functionality for Presto C++.
126+
127+
.. _native-sidecar-plugin:
128+
129+
Native Sidecar Plugin
130+
---------------------
131+
132+
The ``NativeSidecarPlugin`` class implements ``CoordinatorPlugin`` interface
133+
and returns the following service providers via their respective provider
134+
factories.
135+
136+
+----------------------+----------------------------------------------+---------------------------------------+
137+
| Service | Native Provider Factory | Native Service Provider |
138+
+======================+==============================================+=======================================+
139+
| Session Properties | NativeSystemSessionPropertyProviderFactory | NativeSystemSessionPropertyProvider |
140+
+----------------------+----------------------------------------------+---------------------------------------+
141+
| Functions | NativeFunctionNamespaceManagerFactory | NativeFunctionNamespaceManager |
142+
+----------------------+----------------------------------------------+---------------------------------------+
143+
| Types | NativeTypeManagerFactory | NativeTypeManager |
144+
+----------------------+----------------------------------------------+---------------------------------------+
145+
| Plan Checker | NativePlanCheckerProviderFactory | NativePlanCheckerProvider |
146+
+----------------------+----------------------------------------------+---------------------------------------+
147+
148+
For instance, the class ``NativeSystemSessionPropertyProviderFactory``
149+
implements the interface ``WorkerSessionPropertyProviderFactory`` in Presto SPI
150+
to return the service provider, ``NativeSystemSessionPropertyProvider``. The class
151+
``NativeSystemSessionPropertyProvider`` retrieves all session properties
152+
supported by the Presto C++ worker by making a REST call to the endpoint
153+
``/v1/properties/session`` on the Presto C++ sidecar. ``NativeSidecarPlugin``,
154+
therefore, needs at least one Presto C++ worker in the cluster to be configured
155+
as a sidecar. See :doc:`/presto_cpp/sidecar` for more details.

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

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ Note: Presto C++ is in active development. See :doc:`Limitations </presto_cpp/li
88
:maxdepth: 1
99

1010
presto_cpp/features
11+
presto_cpp/sidecar
1112
presto_cpp/limitations
1213
presto_cpp/properties
1314
presto_cpp/properties-session
@@ -19,11 +20,19 @@ Presto C++, sometimes referred to by the development name Prestissimo, is a
1920
drop-in replacement for Presto workers written in C++ and based on the
2021
`Velox <https://velox-lib.io/>`_ library.
2122
It implements the same RESTful endpoints as Java workers using the Proxygen C++
22-
HTTP framework.
23+
HTTP framework.
2324
Because communication with the Java coordinator and across workers is only
2425
done using the REST endpoints, Presto C++ does not use JNI and does not
2526
require a JVM on worker nodes.
2627

28+
A Presto C++ worker can be configured as a sidecar to customize the Java
29+
coordinator's functionality for Presto C++ clusters. The Presto C++ sidecar
30+
implements additional REST endpoints to provide the coordinator more
31+
information about the Presto C++ worker, such as session properties and
32+
functions, via the ``NativeSidecarPlugin``. It is recommended to configure
33+
at least one worker in the Presto C++ cluster as a sidecar. See :doc:`presto_cpp/sidecar`
34+
and :ref:`native-sidecar-plugin` for more details.
35+
2736
Presto C++'s codebase is located at `presto-native-execution
2837
<https://github.com/prestodb/presto/tree/master/presto-native-execution>`_.
2938

‎presto-docs/src/main/sphinx/presto_cpp/sidecar.rst‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
===================
2+
Presto C++ Sidecar
3+
===================
4+
5+
.. contents::
6+
:local:
7+
:backlinks: none
8+
:depth: 1
9+
10+
Endpoints
11+
---------
12+
13+
The following HTTP endpoints are implemented by the Presto C++ sidecar.
14+
15+
.. function:: GET /v1/properties/session
16+
17+
Returns a list of system session properties supported by the Presto C++
18+
worker. Each session property is serialized to JSON in format
19+
``SessionPropertyMetadata``.
20+
21+
.. function:: GET /v1/functions
22+
23+
Returns a list of function metadata for all functions registered in the
24+
Presto C++ worker. Each function's metadata is serialized to JSON in
25+
format ``JsonBasedUdfFunctionMetadata``.
26+
27+
.. function:: POST /v1/velox/plan
28+
29+
Converts a Presto plan fragment to its corresponding Velox plan and
30+
validates the Velox plan. Returns any errors encountered during plan
31+
conversion.
32+
33+
Configuration Properties
34+
------------------------
35+
36+
The following properties should be set on the Presto C++ sidecar:
37+
38+
``native-sidecar``
39+
^^^^^^^^^^^^^^^^^^^
40+
41+
* **Type:** ``boolean``
42+
* **Default value:** ``false``
43+
44+
Set this to ``true`` to configure the Presto C++ worker as a sidecar.
45+
46+
``presto.default-namespace``
47+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
48+
49+
* **Type:** ``string``
50+
* **Default value:** ``"native.default"``
51+
52+
All functions registered in Presto are named in format ``catalog.schema.function_name``,
53+
this property defines the prefix used to register all Presto C++ functions.
54+
The default namespace should be of type ``catalog.schema`` and it is
55+
recommended to set it to ``native.default``.

0 commit comments

Comments
 (0)