Add SODA to tutorial; tweak defaults used in samples.

Author: anthony-tuininga

samples/SampleEnv.py

@@ -29,7 +29,7 @@
 #   [//]host_name[:port][/service_name][:server_type][/instance_name]
 #
 # Commonly just the host_name and service_name are needed
-# e.g. "localhost/orclpdb" or "localhost/XE"
+# e.g. "localhost/orclpdb1" or "localhost/XE"
 #
 # If using a tnsnames.ora file, the file can be in a default
 # location such as $ORACLE_HOME/network/admin/tnsnames.ora or
@@ -53,7 +53,7 @@
 DEFAULT_MAIN_USER = "pythondemo"
 DEFAULT_EDITION_USER = "pythoneditions"
 DEFAULT_EDITION_NAME = "python_e1"
-DEFAULT_CONNECT_STRING = "localhost/orclpdb"
+DEFAULT_CONNECT_STRING = "localhost/orclpdb1"
 
 # dictionary containing all parameters; these are acquired as needed by the
 # methods below (which should be used instead of consulting this dictionary

samples/tutorial/Python-and-Oracle-Database-Scripting-for-the-Future.html

@@ -92,6 +92,12 @@ <h2>Contents</h2>
           <li>10.1 Message passing with Oracle Advanced Queuing</li>
         </ul>
       </li>
+      <li><a href="#soda" >11. Simple Oracle Document Access (SODA)</a>
+        <ul>
+          <li>11.1 Inserting JSON Documents</li>
+          <li>11.2 Searching SODA Documents</li>
+        </ul>
+      </li>
     </ul>
     <li><a href="#summary" >Summary</a></li>
     <li><a href="#primer" >Appendix: Python Primer</a></li>
@@ -100,24 +106,27 @@ <h2>Contents</h2>
 
   <h2><a name="preface">Preface</a></h2>
 
-  <p>If you are running this tutorial in your own environment, install the following required software:</p>
+  <p>If you are running this tutorial in your own environment, install the required software:</p>
 
 <ol>
-  <li><a target="_blank" href="https://www.python.org/">Python</a> (3.6 preferred but 2.7 should work)</li>
-  <li>cx_Oracle (version 7.2 preferred but 6.3 or later should work, except for the section on Advanced Queuing which requires version 7.2 or later) and Oracle Instant Client Package - Basic (version 19.3 preferred but 18.3 or 12.2 should also work)
+  <li><p><a target="_blank" href="https://www.python.org/">Python</a>. Version 3.6 is preferred.</p></li>
+  <li><p>cx_Oracle version 7.2 and the Oracle Client libraries.</p>
     <ul>
       <li><a target="_blank" href="http://cx-oracle.readthedocs.io/en/latest/installation.html#installing-cx-oracle-on-linux">Linux</a></li>
       <li><a target="_blank" href="http://cx-oracle.readthedocs.io/en/latest/installation.html#installing-cx-oracle-on-macos">macOS</a> - please note the special instructions for macOS in the link.</li>
       <li><a target="_blank" href="http://cx-oracle.readthedocs.io/en/latest/installation.html#installing-cx-oracle-on-windows">Windows</a></li>
     </ul>
   </li>
-  <li>Oracle <a target="_blank" href="http://www.oracle.com/technetwork/database/database-technologies/instant-client/overview/index.html">Instant Client Package - SQL*Plus</a>.</li>
+
+  <li><p>SQL*Plus such as from the Oracle <a target="_blank" href="http://www.oracle.com/technetwork/database/database-technologies/instant-client/overview/index.html">Instant Client SQL*Plus Package</a>.</p></li>
 </ol>
 
+<p>The Advanced Queuing section requires Oracle client 12.2 or later.  The SODA section requires Oracle client 18.5, or later, and Oracle Database 18 or later.</p>
+
 <p>To create the schema run:</p>
 
 <pre>
-sqlplus sys/yoursyspassword@localhost/orclpdb as sysdba @sql/SetupSamples
+sqlplus sys/yoursyspassword@localhost/orclpdb1 as sysdba @sql/SetupSamples
 </pre>
 
   <h2><a name="connectioninformation">Connection Information</a></h2>
@@ -130,11 +139,11 @@ <h2><a name="connectioninformation">Connection Information</a></h2>
   </p>
 
   <p>The username is "pythonhol" with
-  the password "welcome".  The connect string is "localhost/orclpdb".
+  the password "welcome".  The connect string is "localhost/orclpdb1".
   See <code>sql/SampleEnv.sql</code>.</p>
 
   <p>It is easist to have a local pluggable database with the service
-  'orclpdb' configured.  If your database is not local, or has a
+  'orclpdb1' configured.  If your database is not local, or has a
   different service, you will need to modify the connection information in db_config.py and db_config.sql.</p>
 
   <p>The following sections may need adjusting, depending on how you
@@ -174,16 +183,16 @@ <h4>1.1 Review the connection credentials</h4>
           <pre>
 user = "pythonhol"
 pw = "welcome"
-dsn = "localhost/orclpdb"
+dsn = "localhost/orclpdb1"
 </pre>
  <code>db_config.sql</code>
            <pre>
 def user = "pythonhol"
 def pw = "welcome"
-def connect_string = "localhost/orclpdb"
+def connect_string = "localhost/orclpdb1"
           </pre>
 
-          <p>By default they connect to the 'orclpdb' database service on the same machine as Python.  You can modify the values in both files to match the connection information for your environment.</p>
+          <p>By default they connect to the 'orclpdb1' database service on the same machine as Python.  You can modify the values in both files to match the connection information for your environment.</p>
 
         </li>
 
@@ -207,7 +216,7 @@ <h4>1.2 Creating a basic connection</h4>
           the db_config.py module. In this case, Oracle's Easy Connect connection
           string syntax is used. It consists of the hostname of your
           machine, <code>localhost</code>, and the database service name
-          <code>orclpdb</code>. </p>
+          <code>orclpdb1</code>. </p>
 
           <p>Open a command terminal and change to the <code>tutorial</code> directory:</p>
 
@@ -1128,7 +1137,7 @@ <h4>2.5 More DRCP investigation</h4>
   <p>In a terminal window, start SQL*Plus using the lab credentials and connection string, such as:</p>
 
   <pre>
-sqlplus pythonhol/welcome@localhost/orclpdb
+sqlplus pythonhol/welcome@localhost/orclpdb1
 </pre>
 
   <p>Use the SQL*Plus DESCRIBE command to look at the SDO definition:</p>
@@ -1661,6 +1670,9 @@ <h4>6.1 Basic output type handler</h4>
 
 <li><h3><a name="lobs">7. LOBs</a></h3>
 
+  <p>Oracle Database "LOB" long objects can be streamed using a LOB
+  locator, or worked with directly as strings or bytes.</p>
+
   <ul>
     <li>
     <h4>7.1 Fetching a CLOB using a locator</h4>
@@ -1694,8 +1706,8 @@ <h4>7.1 Fetching a CLOB using a locator</h4>
 </pre>
 
       <p>This inserts some test string data and then fetches one
-      record into <code>clob</code>, which is a cx_Oracle LOB Object.
-      Methods on LOB include <code>size()</code> and
+      record into <code>clob</code>, which is a cx_Oracle character
+      LOB Object.  Methods on LOB include <code>size()</code> and
       <code>read()</code>.</p>
 
       <p>To see the output, run the file:</p>
@@ -1947,7 +1959,7 @@ <h4>7.2 Fetching a CLOB as a string</h4>
 
 <li><h3><a name="aq">10. Advanced Queuing</a></h3>
   <ul>
-    <li><h4>10.1 Message passing with Oracle Advanced Queuing</h4></li>
+    <li><h4>10.1 Message passing with Oracle Advanced Queuing</h4>
 
     <p>Review <code>aq.py</code>:</p>
 
@@ -2074,6 +2086,114 @@ <h4>7.2 Fetching a CLOB as a string</h4>
 </ul>
 </li>
 
+</li>
+
+<li><h3><a name="soda">11. Simple Oracle Document Access (SODA)</a></h3>
+
+  <p>Simple Oracle Document Access is a set of NoSQL-style APIs.
+  Documents can be inserted, queried, and retrieved from Oracle
+  Database.  By default, documents are JSON strings.  SODA APIs
+  exist in many languages.</p>
+
+  <ul>
+
+    <li><h4>11.1 Inserting JSON Documents</h4>
+
+      <p>Review <code>soda.py</code>:</p>
+
+<pre>
+import cx_Oracle
+import db_config
+
+con = cx_Oracle.connect(db_config.user, db_config.pw, db_config.dsn)
+
+soda = con.getSodaDatabase()
+
+collection = soda.createCollection("friends")
+
+content = {'name': 'Jared', 'age': 35, 'address': {'city': 'Melbourne'}}
+
+doc = collection.insertOneAndGet(content)
+key = doc.key
+
+doc = collection.find().key(key).getOne()
+content = doc.getContent()
+print('Retrieved SODA document dictionary is:')
+print(content)
+</pre>
+
+      <p><code>soda.createCollection()</code> will create a new
+      collection, or open an existing collection, if the name is
+      already in use.</p>
+
+      <p><code>insertOneAndGet()</code> inserts the content of a
+      document into the database and returns a SODA Document Object.
+      This allows access to meta data such as the document key.  By
+      default, document keys are automatically generated.</p>
+
+      <p>The <code>find()</code> method is used to begin an operation
+      that will act upon documents in the collection.</p>
+
+      <p><code>content</code> is a dictionary.  You can also get a JSON string
+      by calling <code>doc.getContentAsString()</code>.</p>
+
+      <p>Run the file:</p>
+
+<pre><strong>python soda.py</strong></pre>
+
+      <p>The output shows the content of the new document.</p>
+
+    </li>
+
+    <li><h4>11.2 Searching SODA Documents</h4>
+
+      <p>Extend <code>soda.py</code> to insert some more documents and
+      perform a find filter operation:</p>
+
+<pre>
+myDocs = [
+    {'name': 'Gerald', 'age': 21, 'address': {'city': 'London'}},
+    {'name': 'David', 'age': 28, 'address': {'city': 'Melbourne'}},
+    {'name': 'Shawn', 'age': 20, 'address': {'city': 'San Francisco'}}
+]
+collection.insertMany(myDocs)
+
+filterSpec = { "address.city": "Melbourne" }
+myDocuments = collection.find().filter(filterSpec).getDocuments()
+
+print('Melbourne people:')
+for doc in myDocuments:
+    print(doc.getContent()["name"])
+</pre>
+
+      <p>Run the script again:</p>
+
+      <pre><strong>python soda.py</strong></pre>
+
+      <p>The find operation filters the collection and returns
+      documents where the city is Melbourne.  Note the
+      <code>insertMany()</code> method is currently in preview.</p>
+
+      <p>SODA supports query by example (QBE) with an extensive set of
+      operators.  Extend <code>soda.py</code> with a QBE to find
+      documents where the age is less than 25:</p>
+
+<pre>
+filterSpec = {'age': {'$lt': 25}}
+myDocuments = collection.find().filter(filterSpec).getDocuments()
+
+print('Young people:')
+for doc in myDocuments:
+    print(doc.getContent()["name"])
+</pre>
+
+<p>Running the script displays the names.</p>
+
+    </li>
+  </ul>
+
+</li>
+
 </ol>
 
   <h2><a name="summary">Summary</a></h2>
@@ -2307,7 +2427,7 @@ <h2><a name="resources">Resources</a></h2>
 <div class="footer"></div>
 <table border="0" cellpadding="10" cellspacing="0" width="100%">
   <tbody><tr>
-    <td align="right" width="54%">Copyright &copy; 2017, Oracle and/or its affiliates. All rights reserved</td>
+    <td align="right" width="54%">Copyright &copy; 2017, 2019, Oracle and/or its affiliates. All rights reserved</td>
   </tr>
   <tr><td colspan="2"></td></tr>
   </tbody>

samples/tutorial/db_config.py

@@ -1,3 +1,3 @@
 user = "pythonhol"
 pw = "welcome"
-dsn = "localhost/orclpdb"
+dsn = "localhost/orclpdb1"

samples/tutorial/db_config.sql

@@ -1,3 +1,3 @@
 def user = "pythonhol"
 def pw = "welcome"
-def connect_string = "localhost/orclpdb"
+def connect_string = "localhost/orclpdb1"

samples/tutorial/soda.py

@@ -0,0 +1,28 @@
+#------------------------------------------------------------------------------
+# soda.py (Section 11.1)
+#------------------------------------------------------------------------------
+
+#------------------------------------------------------------------------------
+# Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
+#------------------------------------------------------------------------------
+
+from __future__ import print_function
+
+import cx_Oracle
+import db_config
+
+con = cx_Oracle.connect(db_config.user, db_config.pw, db_config.dsn)
+
+soda = con.getSodaDatabase()
+
+collection = soda.createCollection("friends")
+
+content = {'name': 'Jared', 'age': 35, 'address': {'city': 'Melbourne'}}
+
+doc = collection.insertOneAndGet(content)
+key = doc.key
+
+doc = collection.find().key(key).getOne()
+content = doc.getContent()
+print('Retrieved SODA document dictionary is:')
+print(content)

samples/tutorial/solutions/soda.py

@@ -0,0 +1,49 @@
+#------------------------------------------------------------------------------
+# soda.py (Section 11.2)
+#------------------------------------------------------------------------------
+
+#------------------------------------------------------------------------------
+# Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
+#------------------------------------------------------------------------------
+
+from __future__ import print_function
+
+import cx_Oracle
+import db_config
+
+con = cx_Oracle.connect(db_config.user, db_config.pw, db_config.dsn)
+
+soda = con.getSodaDatabase()
+
+collection = soda.createCollection("friends")
+
+content = {'name': 'Jared', 'age': 35, 'address': {'city': 'Melbourne'}}
+
+doc = collection.insertOneAndGet(content)
+key = doc.key
+
+doc = collection.find().key(key).getOne()
+content = doc.getContent()
+print('Retrieved SODA document dictionary is:')
+print(content)
+
+myDocs = [
+    {'name': 'Gerald', 'age': 21, 'address': {'city': 'London'}},
+    {'name': 'David', 'age': 28, 'address': {'city': 'Melbourne'}},
+    {'name': 'Shawn', 'age': 20, 'address': {'city': 'San Francisco'}}
+]
+collection.insertMany(myDocs)
+
+filterSpec = { "address.city": "Melbourne" }
+myDocuments = collection.find().filter(filterSpec).getDocuments()
+
+print('Melbourne people:')
+for doc in myDocuments:
+    print(doc.getContent()["name"])
+
+filterSpec = {'age': {'$lt': 25}}
+myDocuments = collection.find().filter(filterSpec).getDocuments()
+
+print('Young people:')
+for doc in myDocuments:
+    print(doc.getContent()["name"])

samples/tutorial/sql/SetupSamples.sql

@@ -38,6 +38,19 @@ to &main_user;
 grant execute on dbms_aqadm to &main_user;
 grant execute on dbms_lock to &main_user;
 
+begin
+
+    for r in
+            ( select role
+              from dba_roles
+              where role in ('SODA_APP')
+            ) loop
+        execute immediate 'grant ' || r.role || ' to &main_user';
+    end loop;
+
+end;
+/
+
 create table &main_user..testclobs (
     id     number not null,
     myclob clob not null