5.10 About Interpreter Bindings and Notebooks

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 these 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 bindings that define the order of the interpreter bindings 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 execute 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 execute 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.

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 Interpreter Bindings for Specific Paragraphs in a Notebook
  The interpreter binding order that is set for a notebook applies to all the paragraphs in that notebook. However, you can override the interpreter binding for SQL, PL/SQL, R, Python and Conda interpreters for any specific paragraph in the notebook.
• Set Interpreter Bindings for Notebooks
  You must bind a notebook to an interpreter to fetch data from the database or any data source. A default set of interpreter bindings is available.
• Verify Interpreter Bindings
  After setting and changing the order of interpreter bindings, you can verify the interpreter bindings whether you are using SQL, PL/SQL, R or Python interpreter in a given notebook. You use a SQL statement to view and verify the interpreter binding information about your notebook.

5.10.1 Change Interpreter Bindings for Specific Paragraphs in a Notebook

The interpreter binding order that is set for a notebook applies to all the paragraphs in that notebook. However, you can override the interpreter binding for SQL, PL/SQL, R, Python and Conda interpreters for any specific paragraph in the notebook.

To use these 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

Note:

Do not override Python paragraph interpreter bindings as they will not share the same Python engine backend.

To change the interpreter binding for a specific paragraph in a notebook:

1. Open the notebook and click the gear icon to view the interpreter bindings and its order.
   
   In this example, all the three SQL interpreters are bound to the notebook, and the interpreter with low resource allocation adwpcwdp_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 order name.
   In this example, the interpreter names are:
   • adwp_low % sql(default),%script, %python, %r, %conda
   • adwp_medium % sql(default),%script, %python, %r, %conda
   • adwp_high % sql(default), %script,%python, %r, %conda
   • md %md(default)

   Figure 5-9 Interpreter Bindings

   
   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, adwp_low. If any Python scripts run queries against the database, then those queries are run using the low database name service, that is, adwp_low in this example.
2. To change the interpreter bindings order for a particular paragraph in the notebook:
   • Scroll down to the paragraph for which you want to change the interpreter
   • Call the interpreter with the specific binding
   • Run the paragraph
   For example, call the interpreter with medium resource allocation by typing %adwp_medium for the first paragraph in the notebook, and run the paragraph. In this example, adwp is the database name.
   
   Notice that the first paragraph runs without any error after changing the interpreter binding. The second paragraph in this notebook has the default binding.
3. Validate the interpreter binding for first paragraph of this notebook by typing the SQL statement SELECT SYS_CONTEXT ('USERENV', 'SERVICE_NAME') FROM DUAL;
   The SQL statement returns the following information about the interpreter with medium binding:

   LGKFDTOOBOQK48I_CWDP_medium.adwc.oraclecloud.com

   
   In this example, with reference to the screenshot:

   • LGKFDTOOBOQK48I is the tenant name
   • CWDP is the database name
   • medium is the service name
   • adwc.oraclecloud.com is the domain

   Note:

   For the rest of the paragraphs in this notebook, the interpreter binding is the default. You may validate the bindings for each paragraph by running step 3.
   This completes the task of changing the interpreter binding for a particular paragraph in the notebook. The rest of the paragraphs in the notebook have the default binding for the interpreter.

5.10.2 Set Interpreter Bindings for Notebooks

You must bind a notebook to an interpreter to fetch data from the database or any data source. A default set of interpreter bindings is available.

You can set the order of interpreter bindings if you have more than one set available. To set the order of interpreter bindings:

1. On the Notebook page, click the notebook for which you want to set the interpreter bindings.
   The notebook opens in edit mode.
2. Click the gear icon at the top panel.
   
   The Settings pane opens listing the interpreter bindings for the notebook.
3. Drag and drop the interpreters to reorder the interpreter bindings. The first interpreter on the list is the default. The order of interpreter bindings is:
   • Low (Default): 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 execute 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.
   This is the initial binding order of the interpreters. You can change the order of the interpreter bindings.
4. Click Save.

5.10.3 Verify Interpreter Bindings

After setting and changing the order of interpreter bindings, you can verify the interpreter bindings whether you are using SQL, PL/SQL, R or Python interpreter in a given notebook. You use a SQL statement to view and verify the interpreter binding information about your notebook.

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.

To verify the interpreter binding of notebooks:

1. Open the notebook for which you want to check the interpreter binding.
2. Run the following SQL statement:

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

   The SQL statement provides the name of the service to which a given session is connected.

3. Click Run.
   The SQL statement returns the information about the interpreter, the order of the binding, and the service name. The result is displayed in the following format tenantname__databasename_ servicename.domain. Here:

   • HDY7RUSKGDMPHN2 is the tenant name
   • PDB1 is the database name
   • low is the interpreter binding order
   • adwc.oraclecloud.com is the domain name