About Interpreters and Notebook Service Levels

4.13 About Interpreters and Notebook Service Levels

An interpreter is a plug-in that allows you to use a specific data processing language backend.

For the Zeppelin Notebooks in Oracle Machine Learning UI, you use the SQL, PL/SQL, Python and R interpreters within an Oracle Database interpreter group, and the Markdown interpreter for plain text formatting syntax so that it can be converted to HTML. You use the Conda interpreter to connect to the Conda environment and work with Python third-party library packages.

To use the interpreters, you must use these directives at the beginning of the paragraph in a notebook

SQL — %sql
PL/SQL — %script
Python — %python
R - %r
Markdown — %md
Conda — %conda

Notebooks contain an internal list of service levels that define the order of the interpreters in an interpreter group. The default order of interpreter bindings in the Oracle Database interpreter group is:

low — Provides the least level of resources for in-database operations, typically serial (non-parallel) execution. It supports the maximum number of concurrent in-database operations by multiple users. The interpreter with low priority is listed at the top of the interpreter list, and hence, is the default.
medium — Provides a fixed number of CPUs to run in-database operations in parallel, where possible. It supports a limited number of concurrent users, typically 1.25 times the number of CPUs allocated to the pluggable database.
high — Provides the highest level of CPUs to run in-database operations in parallel, up to the number of CPUs allocated to the pluggable database. It offers the highest performance, but supports the minimum number of concurrent in-database operations, typically 3.
gpu — Provides GPU compute capabilities in a notebook through the Python interpreter with the database service level set to high. The memory settings is 8 GB (DDR4), by default. It is extensible up to 200 GB.

With respect to interpreter bindings, you can perform the following tasks:

Bind and unbind interpreters: If you do not bind any specific interpreter to your notebook, then you get the error message:
```
Not supported interpreter <name of interpreter>
```
Set and re-order interpreter bindings. You may want to set and re-order interpreter bindings if you want to use a specific interpreter for a specific paragraph in a notebook. In that case, you have to select the specific interpreter for that paragraph.
Change the interpreter binding for any specific paragraph in a notebook

You must note the interpreter binding order in the following scenarios:

Notebook creation — When you create a notebook, the notebook inherits the initial interpreter binding order, which is low (default), medium, high.
Notebook import — When importing a notebook, the notebook inherits the defined interpreter bindings. However, after you import a notebook, ensure to check the order of the interpreter bindings and that the required interpreters are selected.
Notebook export — When exporting a notebook, the notebook inherits the defined interpreter bindings.
Notebook creation from templates — When you create a notebook from templates, the notebook inherits the default order of interpreter bindings.

Change Notebook Service Level
Notebook type corresponds to the ADB service levels — low, medium, high and gpu. These service levels affect parallelism in the database. The notebook type that is set for a notebook applies to all the paragraphs in that notebook.
Verify Notebook Service Level
After changing the Notebook service level, you can use a SQL statement to view and verify the information. Notebook type, referred to as interpreter bindings in Notebooks Classic, corresponds to the ADB service levels — low, medium, high and gpu. These service levels affect parallelism in the database.

Parent topic: OML Notebooks

4.13.1 Change Notebook Service Level

Notebook type corresponds to the ADB service levels — low, medium, high and gpu. These service levels affect parallelism in the database. The notebook type that is set for a notebook applies to all the paragraphs in that notebook.

Note:

In Notebooks Classic, the notebook type is referred to as the interpreter bindings. The notebook type gpu is not available in Notebooks Classic.

To use the interpreters, you must use these directives at the beginning of a paragraph in a notebook

SQL — %sql
PL/SQL — %script
Python — %python
R — %r
Markdown — %md
Conda — %conda

You can change notebook service levels in both the new Notebook and Notebooks Classic.

Change Notebook Service Level in the new Notebook

Open your notebook in the notebook editor.
Click on the Update Notebook Type icon on the top right corner. The available notebook types are displayed. The current notebook type is indicated by a tick mark, and is also displayed next to the Update Notebook Type icon.

Figure 4-58 ADB service levels as displayed in a notebook
The Notebook Types (ADB service levels) are:
- low —Provides the least level of resources for in-database operations, typically serial (non-parallel) execution. It supports the maximum number of concurrent in-database operations by multiple users. The interpreter with low priority is listed at the top of the interpreter list, and hence, is the default.
- medium—Provides a fixed number of CPUs to run in-database operations in parallel, where possible. It supports a limited number of concurrent users, typically 1.25 times the number of CPUs allocated to the pluggable database.
- high—Provides the highest level of CPUs to run in-database operations in parallel, up to the number of CPUs allocated to the pluggable database. It offers the highest performance, but supports the minimum number of concurrent in-database operations, typically 3.
- gpu—Provides GPU compute capabilities in a notebook through the Python interpreter with the database service level set to high. The notebook memory setting is 32 GB (DDR4), by default. It is extensible up to 200 GB.
To change the notebook type, click on the type that you want to select. In this example, let's click high. A confirmation message is displayed stating: Notebook Type is updated to "high".

Note:
The updated notebook type is applicable to all the paragraphs in the notebook. You cannot change the notebook type at the paragraph level.

Figure 4-59 ADB service level - high

Change Interpreter Bindings (Notebook Type) in Notebooks Classic

Click the gear icon to view the interpreter bindings (ADB service levels) and its order.

Note:
The notebook type gpu is not available in Notebooks Classic.
The interpreter bindings are displayed as shown in the screenshot here:

Figure 4-60 Interpreter Bindings specified through Notebooks Classic

In this example, all the three SQL interpreters are bound to the notebook, and the interpreter with ADB service level low resource allocation OMLLABS104047_low %sql is the default, as it is the first interpreter on the list. The Markdown interpreter is not bound to the notebook

Note:
The names of the interpreters are in the format databasename_low, databasename_medium and databasename_high which is the same as the interpreter binding name.

In this example, the interpreter names are:
- OMLLABS104047_low % sql(default),%script, %python, %r, %conda
- OMLLABS104047_medium % sql(default),%script, %python, %r, %conda
- OMLLABS104047_high % sql(default), %script,%python, %r, %conda
- md %md(default)
The first Python interpreter in the list is used to run all Python paragraphs in the notebook. For example, if the low binding is selected, then all Python paragraphs are run using the low binding Python interpreter. All the other paragraphs with SQL and Script interpreter bindings are run using the low database name service, that is, OMLLABS104047_low. If any Python scripts run queries against the database, then those queries are run using the low database name service, that is, OMLLABS104047_low in this example.
To change the interpreter binding, drag the interpreter binding and drop it at the top of the list. In this example, drag and drop the interpreter OMLLABS104047_high at the top of the list.

Figure 4-61 Interpreter Bindings set to high in Notebooks Classic
Click Save. The updated interpreter binding is applicable to all the paragraphs in the notebook. You cannot change the interpreter binding at the paragraph level.

Parent topic: About Interpreters and Notebook Service Levels

4.13.2 Verify Notebook Service Level

After changing the Notebook service level, you can use a SQL statement to view and verify the information. Notebook type, referred to as interpreter bindings in Notebooks Classic, corresponds to the ADB service levels — low, medium, high and gpu. These service levels affect parallelism in the database.

For Python notebooks, the interpreter binding is used for all python paragraphs.

Note:

For Python notebooks, do not override the interpreter binding at the paragraph level.

Verify Notebook Service Level in a Notebook

Open the notebook for which you want to verify the updated notebook type.

Run the following SQL statement:

%sql
SELECT SYS_CONTEXT ('USERENV', 'SERVICE_NAME') FROM DUAL;

Click Run. The SQL statement returns the following information about the updated notebook type, as shown in the screenshot below:

Figure 4-62 ADB service level information as displayed in a notebook

You can see that the service level is now displayed as high. In this example:

HMUGVWHGDA3DBYM is the tenant name
OMLLABS104047 is the database name
high is the ADB service name
adb.oraclecloud.com is the domain

Verify Interpreter Bindings in Notebooks Classic

Open the Notebooks Classic for which you want to validate the updated interpreter bindings.

Run the following SQL statement:

%sql
SELECT SYS_CONTEXT ('USERENV', 'SERVICE_NAME') FROM DUAL;

The SQL statement returns the following information about the updated interpreter bindings, as shown in the screenshot below:

Figure 4-63 ADB service level information as displayed in Notebooks Classic

You can see that the service level is now displayed as high. In this example:

HMUGVWHGDA3DBYM is the tenant name
OMLLABS104047 is the database name
high is the ADB service name
adb.oraclecloud.com is the domain

Parent topic: About Interpreters and Notebook Service Levels