Skip to content

Commit 64f6505

Browse files
anthony-tuiningaanthony-tuininga
committed
Add support (as preview) for SODA.
1 parent b611246 commit 64f6505

22 files changed

+2957
-0
lines changed

‎doc/src/connection.rst‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -280,6 +280,26 @@ Connection Object
280280
This attribute is an extension to the DB API definition.
281281

282282

283+
.. method:: Connection.getSodaDatabase()
284+
285+
Return a :ref:`SodaDatabase <sodadb>` object for Simple Oracle Document
286+
Access (SODA). All SODA operations are performed either on the returned
287+
SodaDatabase object or from objects created by SodaDatabase. See
288+
`here <http://www.oracle.com/pls/topic/lookup?
289+
ctx=dblatest&id=GUID-BE42F8D3-B86B-43B4-B2A3-5760A4DF79FB>`__ for
290+
additional information on SODA.
291+
292+
SODA support in cx_Oracle is in Preview status and should not be used in
293+
production. It will be supported with a future version of Oracle Client
294+
libraries.
295+
296+
.. versionadded:: 7.0
297+
298+
.. note::
299+
300+
This method is an extension to the DB API definition.
301+
302+
283303
.. method:: Connection.gettype(name)
284304

285305
Return a :ref:`type object <objecttype>` given its name. This can then be

‎doc/src/index.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,11 @@ Contents:
2424
lob.rst
2525
objecttype.rst
2626
aq.rst
27+
sodadb.rst
28+
sodacoll.rst
29+
sodaop.rst
30+
sodadoc.rst
31+
sodadoccur.rst
2732
whatsnew.rst
2833
releasenotes.rst
2934
license.rst

‎doc/src/sodacoll.rst‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
.. _sodacoll:
2+
3+
**********************
4+
SODA Collection Object
5+
**********************
6+
7+
.. note::
8+
9+
This object is an extension the DB API. It is used to represent SODA
10+
collections and is created by methods
11+
:meth:`SodaDatabase.createCollection()` and
12+
:meth:`SodaDatabase.openCollection()`.
13+
14+
SODA support in cx_Oracle is in Preview status and should not be used in
15+
production. It will be supported with a future version of Oracle Client
16+
libraries.
17+
18+
19+
.. method:: SodaCollection.createIndex(spec)
20+
21+
Creates an index on a SODA collection. The spec is expected to be a
22+
dictionary or a JSON-encoded string. See this `overview
23+
<https://www.oracle.com/pls/topic/
24+
lookup?ctx=dblatest&id=GUID-4848E6A0-58A7-44FD-8D6D-A033D0CCF9CB>`__
25+
for information on indexes in SODA.
26+
27+
Note that a commit should be performed before attempting to create an
28+
index.
29+
30+
.. versionadded:: 7.0
31+
32+
33+
.. method:: SodaCollection.drop()
34+
35+
Drops the collection from the database, if it exists. Note that if the
36+
collection was created with mapMode set to True the underlying table will
37+
not be dropped.
38+
39+
A boolean value is returned indicating if the collection was actually
40+
dropped.
41+
42+
.. versionadded:: 7.0
43+
44+
45+
.. method:: SodaCollection.dropIndex(name, force=False)
46+
47+
Drops the index with the specified name, if it exists.
48+
49+
The force parameter, if set to True, can be used to force the dropping of
50+
an index that the underlying Oracle Database domain index doesn't normally
51+
permit. This is only applicable to spatial and JSON search indexes.
52+
See `here <https://www.oracle.com/pls/topic/
53+
lookup?ctx=dblatest&id=GUID-F60F75DF-2866-4F93-BB7F-8FCE64BF67B6>`__
54+
for more information.
55+
56+
A boolean value is returned indicating if the index was actually dropped.
57+
58+
.. versionadded:: 7.0
59+
60+
61+
.. method:: SodaCollection.find()
62+
63+
This method is used to begin an operation that will act upon documents in
64+
the collection. It creates and returns a
65+
:ref:`SodaOperation object <sodaop>` which is used to specify the criteria
66+
and the operation that will be performed on the documents that match that
67+
criteria.
68+
69+
.. versionadded:: 7.0
70+
71+
72+
.. method:: SodaCollection.getDataGuide()
73+
74+
Returns a :ref:`SODA document object <sodadoc>` containing property names,
75+
data types and lengths inferred from the JSON documents in the collection.
76+
It can be useful for exploring the schema of a collection. Note that this
77+
method is only supported for JSON-only collections where a JSON search
78+
index has been created with the 'dataguide' option enabled. If there are
79+
no documents in the collection, None is returned.
80+
81+
.. versionadded:: 7.0
82+
83+
84+
.. method:: SodaCollection.insertOne(doc)
85+
86+
Inserts a given document into the collection. The input document can be a
87+
dictionary or list or an existing :ref:`SODA document object <sodadoc>`.
88+
89+
.. versionadded:: 7.0
90+
91+
92+
.. method:: SodaCollection.insertOneAndGet(doc)
93+
94+
Similarly to :meth:`~SodaCollection.insertOne()` this method inserts a
95+
given document into the collection. The only difference is that it
96+
returns a :ref:`SODA Document object <sodadoc>`. Note that for performance
97+
reasons the returned document does not contain the content.
98+
99+
.. versionadded:: 7.0
100+
101+
102+
.. attribute:: SodaCollection.metadata
103+
104+
This read-only attribute returns a dicationary containing the metadata that
105+
was used to create the collection. See this `collection metadata reference
106+
<https://www.oracle.com/pls/topic/
107+
lookup?ctx=dblatest&id=GUID-49EFF3D3-9FAB-4DA6-BDE2-2650383566A3>`__
108+
for more information.
109+
110+
.. versionadded:: 7.0
111+
112+
113+
.. attribute:: SodaCollection.name
114+
115+
This read-only attribute returns the name of the collection.
116+
117+
.. versionadded:: 7.0
118+

‎doc/src/sodadb.rst‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
.. _sodadb:
2+
3+
********************
4+
SODA Database Object
5+
********************
6+
7+
.. note::
8+
9+
This object is an extension the DB API. It is returned by the method
10+
:meth:`Connection.getSodaDatabase()`.
11+
12+
SODA support in cx_Oracle is in Preview status and should not be used in
13+
production. It will be supported with a future version of Oracle Client
14+
libraries.
15+
16+
17+
.. method:: SodaDatabase.createCollection(name, metadata=None, mapMode=False)
18+
19+
Creates a SODA collection with the given name and returns a new
20+
:ref:`SODA collection object <sodacoll>`. If you try to create a
21+
collection, and a collection with the same name and metadata already
22+
exists, then that existing collection is opened without error.
23+
24+
If metadata is specified, it is expected to be a string containing valid
25+
JSON or a dictionary that will be transformed into a JSON string. This JSON
26+
permits you to specify the configuration of the collection including
27+
storage options; specifying the presence or absence of columns for creation
28+
timestamp, last modified timestamp and version; whether the collection can
29+
store only JSON documents; and methods of key and version generation. The
30+
default metadata creates a collection that only supports JSON documents and
31+
uses system generated keys. See this `collection metadata reference
32+
<https://www.oracle.com/pls/topic/
33+
lookup?ctx=dblatest&id=GUID-49EFF3D3-9FAB-4DA6-BDE2-2650383566A3>`__
34+
for more information.
35+
36+
If the mapMode parameter is set to True, the new collection is mapped to an
37+
existing table instead of creating a table. If a collection is created in
38+
this way, dropping the collection will not drop the existing table either.
39+
40+
.. versionadded:: 7.0
41+
42+
43+
.. method:: SodaDatabase.createDocument(content, key=None, mediaType="application/json")
44+
45+
Creates a :ref:`Soda document <sodadoc>` usable for SODA write operations.
46+
You only need to use this method if your collection requires
47+
client-assigned keys or has non-JSON content; otherwise, you can pass your
48+
content directly to SODA write operations. SodaDocument attributes
49+
'createdOn', 'lastModified' and 'version' will be None.
50+
51+
The content parameter can be a dictionary or list which will be transformed
52+
into a JSON string and then UTF-8 encoded. It can also be a string which
53+
will be UTF-8 encoded or it can be a bytes object which will be stored
54+
unchanged. If a bytes object is provided and the content is expected to be
55+
JSON, note that SODA only supports UTF-8, UTF-16LE and UTF-16BE encodings.
56+
57+
The key parameter should only be supplied if the collection in which the
58+
document is to be placed requires client-assigned keys.
59+
60+
The mediaType parameter should only be supplied if the collection in which
61+
the document is to be placed supports non-JSON documents and the content
62+
for this document is non-JSON. Using a standard MIME type for this value is
63+
recommended but any string will be accepted.
64+
65+
.. versionadded:: 7.0
66+
67+
68+
.. method:: SodaDatabase.getCollectionNames(startName=None, limit=0)
69+
70+
Returns a list of the names of collections in the database that match the
71+
criteria, in alphabetical order.
72+
73+
If the startName parameter is specified, the list of names returned will
74+
start with this value and also contain any names that fall after this value
75+
in alphabetical order.
76+
77+
If the limit parameter is specified and is non-zero, the number of
78+
collection names returned will be limited to this value.
79+
80+
.. versionadded:: 7.0
81+
82+
83+
.. method:: SodaDatabase.openCollection(name)
84+
85+
Opens an existing collection with the given name and returns a new
86+
:ref:`SODA collection object <sodacoll>`. If a collection with that name
87+
does not exist, None is returned.
88+
89+
.. versionadded:: 7.0
90+

‎doc/src/sodadoc.rst‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
.. _sodadoc:
2+
3+
********************
4+
SODA Document Object
5+
********************
6+
7+
.. note::
8+
9+
This object is an extension the DB API. It is returned by the methods
10+
:meth:`SodaDatabase.createDocument()`,
11+
:meth:`SodaOperation.getDocuments()` and
12+
:meth:`SodaOperation.getOne()` as well as by iterating over
13+
:ref:`SODA document cursors <sodadoccur>`.
14+
15+
SODA support in cx_Oracle is in Preview status and should not be used in
16+
production. It will be supported with a future version of Oracle Client
17+
libraries.
18+
19+
20+
.. attribute:: SodaDoc.createdOn
21+
22+
This read-only attribute returns the creation time of the document in
23+
`ISO 8601 <https://www.iso.org/iso-8601-date-and-time-format.html>`__
24+
format. Documents created by :meth:`SodaDatabase.createDocument()` or
25+
fetched from collections where this attribute is not stored will return
26+
None.
27+
28+
.. versionadded:: 7.0
29+
30+
31+
.. method:: SodaDoc.getContent()
32+
33+
Returns the content of the document as a dictionary or list. This method
34+
assumes that the content is application/json and will raise an exception if
35+
this is not the case. If there is no content, however, None will be
36+
returned.
37+
38+
.. versionadded:: 7.0
39+
40+
41+
.. method:: SodaDoc.getContentAsBytes()
42+
43+
Returns the content of the document as a bytes object. If there is no
44+
content, however, None will be returned.
45+
46+
.. versionadded:: 7.0
47+
48+
49+
.. method:: SodaDoc.getContentAsString()
50+
51+
Returns the content of the document as a string. This method assumes that
52+
the content is application/json and will raise an exception if this is not
53+
the case. If there is no content, however, None will be returned.
54+
55+
.. versionadded:: 7.0
56+
57+
58+
.. attribute:: SodaDoc.key
59+
60+
This read-only attribute returns the unique key assigned to this document.
61+
Documents created by :meth:`SodaDatabase.createDocument()` may not have a
62+
value assigned to them and return None.
63+
64+
.. versionadded:: 7.0
65+
66+
67+
.. attribute:: SodaDoc.lastModified
68+
69+
This read-only attribute returns the last modified time of the document in
70+
`ISO 8601 <https://www.iso.org/iso-8601-date-and-time-format.html>`__
71+
format. Documents created by :meth:`SodaDatabase.createDocument()` or
72+
fetched from collections where this attribute is not stored will return
73+
None.
74+
75+
.. versionadded:: 7.0
76+
77+
78+
.. attribute:: SodaDoc.mediaType
79+
80+
This read-only attribute returns the media type assigned to the document.
81+
By convention this is expected to be a MIME type but no checks are
82+
performed on this value. If a value is not specified when calling
83+
:meth:`SodaDatabase.createDocument()` or the document is fetched from a
84+
collection where this component is not stored, the string
85+
"application/json" is returned.
86+
87+
.. versionadded:: 7.0
88+
89+
90+
.. attribute:: SodaDoc.version
91+
92+
This read-only attribute returns the version assigned to this document.
93+
Documents created by :meth:`SodaDatabase.createDocument()` or fetched
94+
from collections where this attribute is not stored will return None.
95+
96+
.. versionadded:: 7.0
97+

‎doc/src/sodadoccur.rst‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
.. _sodadoccur:
2+
3+
***************************
4+
SODA Document Cursor Object
5+
***************************
6+
7+
.. note::
8+
9+
This object is an extension the DB API. It is returned by the method
10+
:meth:`SodaOperation.getCursor()` and implements the iterator protocol.
11+
Each iteration will return a :ref:`SODA document object <sodadoc>`.
12+
13+
SODA support in cx_Oracle is in Preview status and should not be used in
14+
production. It will be supported with a future version of Oracle Client
15+
libraries.
16+
17+
18+
.. method:: SodaDocCursor.close()
19+
20+
Close the cursor now, rather than whenever __del__ is called. The cursor
21+
will be unusable from this point forward; an Error exception will be raised
22+
if any operation is attempted with the cursor.
23+
24+
.. versionadded:: 7.0
25+

0 commit comments

Comments
 (0)