HackBase/python-cx_Oracle
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve documentation for SODA.

Browse Source
This commit is contained in:
Anthony Tuininga 2018-09-11 20:50:28 -06:00
parent f647d738a5
commit fc8cfbdf60
8 changed files with 492 additions and 502 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/src/connection.rst
View File

@ -284,8 +284,8 @@ Connection Object
Return a :ref:`SodaDatabase <sodadb>` object for Simple Oracle Document Return a :ref:`SodaDatabase <sodadb>` object for Simple Oracle Document
Access (SODA). All SODA operations are performed either on the returned Access (SODA). All SODA operations are performed either on the returned
SodaDatabase object or from objects created by SodaDatabase. See SodaDatabase object or from objects created by the returned SodaDatabase
`here <http://www.oracle.com/pls/topic/lookup? object. See `here <http://www.oracle.com/pls/topic/lookup?
ctx=dblatest&id=GUID-BE42F8D3-B86B-43B4-B2A3-5760A4DF79FB>`__ for ctx=dblatest&id=GUID-BE42F8D3-B86B-43B4-B2A3-5760A4DF79FB>`__ for
additional information on SODA. additional information on SODA.

6
doc/src/index.rst
View File

@ -24,11 +24,7 @@ Contents:
lob.rst lob.rst
objecttype.rst objecttype.rst
aq.rst aq.rst
sodadb.rst soda.rst
sodacoll.rst
sodaop.rst
sodadoc.rst
sodadoccur.rst
whatsnew.rst whatsnew.rst
releasenotes.rst releasenotes.rst
license.rst license.rst

489
doc/src/soda.rst Normal file
View File

@ -0,0 +1,489 @@
.. _soda:
****
SODA
****
SODA support in cx_Oracle is in Preview status and should not be used in
production. It will be supported with a future version of Oracle Client
libraries.
.. _sodadb:
--------------------
SODA Database Object
--------------------
.. note::
This object is an extension the DB API. It is returned by the method
:meth:`Connection.getSodaDatabase()`.
.. method:: SodaDatabase.createCollection(name, metadata=None, mapMode=False)
Creates a SODA collection with the given name and returns a new
:ref:`SODA collection object <sodacoll>`. If you try to create a
collection, and a collection with the same name and metadata already
exists, then that existing collection is opened without error.
If metadata is specified, it is expected to be a string containing valid
JSON or a dictionary that will be transformed into a JSON string. This JSON
permits you to specify the configuration of the collection including
storage options; specifying the presence or absence of columns for creation
timestamp, last modified timestamp and version; whether the collection can
store only JSON documents; and methods of key and version generation. The
default metadata creates a collection that only supports JSON documents and
uses system generated keys. See this `collection metadata reference
<https://www.oracle.com/pls/topic/
lookup?ctx=dblatest&id=GUID-49EFF3D3-9FAB-4DA6-BDE2-2650383566A3>`__
for more information.
If the mapMode parameter is set to True, the new collection is mapped to an
existing table instead of creating a table. If a collection is created in
this way, dropping the collection will not drop the existing table either.
.. versionadded:: 7.0
.. method:: SodaDatabase.createDocument(content, key=None, mediaType="application/json")
Creates a :ref:`SODA document <sodadoc>` usable for SODA write operations.
You only need to use this method if your collection requires
client-assigned keys or has non-JSON content; otherwise, you can pass your
content directly to SODA write operations. SodaDocument attributes
'createdOn', 'lastModified' and 'version' will be None.
The content parameter can be a dictionary or list which will be transformed
into a JSON string and then UTF-8 encoded. It can also be a string which
will be UTF-8 encoded or it can be a bytes object which will be stored
unchanged. If a bytes object is provided and the content is expected to be
JSON, note that SODA only supports UTF-8, UTF-16LE and UTF-16BE encodings.
The key parameter should only be supplied if the collection in which the
document is to be placed requires client-assigned keys.
The mediaType parameter should only be supplied if the collection in which
the document is to be placed supports non-JSON documents and the content
for this document is non-JSON. Using a standard MIME type for this value is
recommended but any string will be accepted.
.. versionadded:: 7.0
.. method:: SodaDatabase.getCollectionNames(startName=None, limit=0)
Returns a list of the names of collections in the database that match the
criteria, in alphabetical order.
If the startName parameter is specified, the list of names returned will
start with this value and also contain any names that fall after this value
in alphabetical order.
If the limit parameter is specified and is non-zero, the number of
collection names returned will be limited to this value.
.. versionadded:: 7.0
.. method:: SodaDatabase.openCollection(name)
Opens an existing collection with the given name and returns a new
:ref:`SODA collection object <sodacoll>`. If a collection with that name
does not exist, None is returned.
.. versionadded:: 7.0
.. _sodacoll:
----------------------
SODA Collection Object
----------------------
.. note::
This object is an extension the DB API. It is used to represent SODA
collections and is created by methods
:meth:`SodaDatabase.createCollection()` and
:meth:`SodaDatabase.openCollection()`.
.. method:: SodaCollection.createIndex(spec)
Creates an index on a SODA collection. The spec is expected to be a
dictionary or a JSON-encoded string. See this `overview
<https://www.oracle.com/pls/topic/
lookup?ctx=dblatest&id=GUID-4848E6A0-58A7-44FD-8D6D-A033D0CCF9CB>`__
for information on indexes in SODA.
Note that a commit should be performed before attempting to create an
index.
.. versionadded:: 7.0
.. method:: SodaCollection.drop()
Drops the collection from the database, if it exists. Note that if the
collection was created with mapMode set to True the underlying table will
not be dropped.
A boolean value is returned indicating if the collection was actually
dropped.
.. versionadded:: 7.0
.. method:: SodaCollection.dropIndex(name, force=False)
Drops the index with the specified name, if it exists.
The force parameter, if set to True, can be used to force the dropping of
an index that the underlying Oracle Database domain index doesn't normally
permit. This is only applicable to spatial and JSON search indexes.
See `here <https://www.oracle.com/pls/topic/
lookup?ctx=dblatest&id=GUID-F60F75DF-2866-4F93-BB7F-8FCE64BF67B6>`__
for more information.
A boolean value is returned indicating if the index was actually dropped.
.. versionadded:: 7.0
.. method:: SodaCollection.find()
This method is used to begin an operation that will act upon documents in
the collection. It creates and returns a
:ref:`SodaOperation object <sodaop>` which is used to specify the criteria
and the operation that will be performed on the documents that match that
criteria.
.. versionadded:: 7.0
.. method:: SodaCollection.getDataGuide()
Returns a :ref:`SODA document object <sodadoc>` containing property names,
data types and lengths inferred from the JSON documents in the collection.
It can be useful for exploring the schema of a collection. Note that this
method is only supported for JSON-only collections where a JSON search
index has been created with the 'dataguide' option enabled. If there are
no documents in the collection, None is returned.
.. versionadded:: 7.0
.. method:: SodaCollection.insertOne(doc)
Inserts a given document into the collection. The input document can be a
dictionary or list or an existing :ref:`SODA document object <sodadoc>`.
.. versionadded:: 7.0
.. method:: SodaCollection.insertOneAndGet(doc)
Similarly to :meth:`~SodaCollection.insertOne()` this method inserts a
given document into the collection. The only difference is that it
returns a :ref:`SODA Document object <sodadoc>`. Note that for performance
reasons the returned document does not contain the content.
.. versionadded:: 7.0
.. attribute:: SodaCollection.metadata
This read-only attribute returns a dicationary containing the metadata that
was used to create the collection. See this `collection metadata reference
<https://www.oracle.com/pls/topic/
lookup?ctx=dblatest&id=GUID-49EFF3D3-9FAB-4DA6-BDE2-2650383566A3>`__
for more information.
.. versionadded:: 7.0
.. attribute:: SodaCollection.name
This read-only attribute returns the name of the collection.
.. versionadded:: 7.0
.. _sodadoc:
--------------------
SODA Document Object
--------------------
.. note::
This object is an extension the DB API. It is returned by the methods
:meth:`SodaDatabase.createDocument()`,
:meth:`SodaOperation.getDocuments()` and
:meth:`SodaOperation.getOne()` as well as by iterating over
:ref:`SODA document cursors <sodadoccur>`.
.. attribute:: SodaDoc.createdOn
This read-only attribute returns the creation time of the document in
`ISO 8601 <https://www.iso.org/iso-8601-date-and-time-format.html>`__
format. Documents created by :meth:`SodaDatabase.createDocument()` or
fetched from collections where this attribute is not stored will return
None.
.. versionadded:: 7.0
.. method:: SodaDoc.getContent()
Returns the content of the document as a dictionary or list. This method
assumes that the content is application/json and will raise an exception if
this is not the case. If there is no content, however, None will be
returned.
.. versionadded:: 7.0
.. method:: SodaDoc.getContentAsBytes()
Returns the content of the document as a bytes object. If there is no
content, however, None will be returned.
.. versionadded:: 7.0
.. method:: SodaDoc.getContentAsString()
Returns the content of the document as a string. If the document encoding
is not known, UTF-8 will be used. If there is no content, however, None
will be returned.
.. versionadded:: 7.0
.. attribute:: SodaDoc.key
This read-only attribute returns the unique key assigned to this document.
Documents created by :meth:`SodaDatabase.createDocument()` may not have a
value assigned to them and return None.
.. versionadded:: 7.0
.. attribute:: SodaDoc.lastModified
This read-only attribute returns the last modified time of the document in
`ISO 8601 <https://www.iso.org/iso-8601-date-and-time-format.html>`__
format. Documents created by :meth:`SodaDatabase.createDocument()` or
fetched from collections where this attribute is not stored will return
None.
.. versionadded:: 7.0
.. attribute:: SodaDoc.mediaType
This read-only attribute returns the media type assigned to the document.
By convention this is expected to be a MIME type but no checks are
performed on this value. If a value is not specified when calling
:meth:`SodaDatabase.createDocument()` or the document is fetched from a
collection where this component is not stored, the string
"application/json" is returned.
.. versionadded:: 7.0
.. attribute:: SodaDoc.version
This read-only attribute returns the version assigned to this document.
Documents created by :meth:`SodaDatabase.createDocument()` or fetched
from collections where this attribute is not stored will return None.
.. versionadded:: 7.0
.. _sodadoccur:
---------------------------
SODA Document Cursor Object
---------------------------
.. note::
This object is an extension the DB API. It is returned by the method
:meth:`SodaOperation.getCursor()` and implements the iterator protocol.
Each iteration will return a :ref:`SODA document object <sodadoc>`.
.. method:: SodaDocCursor.close()
Close the cursor now, rather than whenever __del__ is called. The cursor
will be unusable from this point forward; an Error exception will be raised
if any operation is attempted with the cursor.
.. versionadded:: 7.0
.. _sodaop:
---------------------
SODA Operation Object
---------------------
.. note::
This object is an extension to the DB API. It represents an operation that
will be performed on all or some of the documents in a SODA collection. It
is created by the method :meth:`SodaCollection.find()`.
.. method:: SodaOperation.count()
Returns a count of the number of documents in the collection that match
the criteria. If :meth:`~SodaOperation.skip()` or
:meth:`~SodaOperation.limit()` were called on this object, an exception is
raised.
.. versionadded:: 7.0
.. method:: SodaOperation.filter(value)
Sets a filter specification for complex document queries and ordering of
JSON documents. Filter specifications must be provided as a dictionary or
JSON-encoded string and can include comparisons, regular expressions,
logical and spatial operators, among others. See the
`overview of SODA filter specifications
<https://www.oracle.com/pls/topic/
lookup?ctx=dblatest&id=GUID-CB09C4E3-BBB1-40DC-88A8-8417821B0FBE>`__
for more information.
As a convenience, the SodaOperation object is returned so that further
criteria can be specified by chaining methods together.
.. versionadded:: 7.0
.. method:: SodaOperation.getCursor()
Returns a :ref:`SODA Document Cursor object <sodadoccur>` that can be used
to iterate over the documents that match the criteria.
.. versionadded:: 7.0
.. method:: SodaOperation.getDocuments()
Returns a list of :ref:`SODA Document objects <sodadoc>` that match the
criteria.
.. versionadded:: 7.0
.. method:: SodaOperation.getOne()
Returns a single :ref:`SODA Document object <sodadoc>` that matches the
criteria. Note that if multiple documents match the criteria only the first
one is returned.
.. versionadded:: 7.0
.. method:: SodaOperation.key(value)
Specifies that the document with the specified key should be returned.
This causes any previous calls made to this method and
:meth:`~SodaOperation.keys()` to be ignored.
As a convenience, the SodaOperation object is returned so that further
criteria can be specified by chaining methods together.
.. versionadded:: 7.0
.. method:: SodaOperation.keys(seq)
Specifies that documents that match the keys found in the supplied sequence
should be returned. This causes any previous calls made to this method and
:meth:`~SodaOperation.key()` to be ignored.
As a convenience, the SodaOperation object is returned so that further
criteria can be specified by chaining methods together.
.. versionadded:: 7.0
.. method:: SodaOperation.limit(value)
Specifies that only the specified number of documents should be returned.
This method is only usable for read operations such as
:meth:`~SodaOperation.getCursor()` and
:meth:`~SodaOperation.getDocuments()`. For write operations, any value set
using this method is ignored.
As a convenience, the SodaOperation object is returned so that further
criteria can be specified by chaining methods together.
.. versionadded:: 7.0
.. method:: SodaOperation.remove()
Removes all of the documents in the collection that match the criteria. The
number of documents that have been removed is returned.
.. versionadded:: 7.0
.. method:: SodaOperation.replaceOne(doc)
Replaces a single document in the collection with the specified document.
The input document can be a dictionary or list or an existing
:ref:`SODA document object <sodadoc>`. A boolean indicating if a document
was replaced or not is returned.
Currently the method :meth:`~SodaOperation.key()` must be called before
this method can be called.
.. versionadded:: 7.0
.. method:: SodaOperation.replaceOneAndGet(doc)
Similarly to :meth:`~SodaOperation.replaceOne()`, this method replaces a
single document in the collection with the specified document. The only
difference is that it returns a :ref:`SODA document object <sodadoc>`.
Note that for performance reasons the returned document does not contain
the content.
.. versionadded:: 7.0
.. method:: SodaOperation.skip(value)
Specifies the number of documents that match the other criteria that will
be skipped. This method is only usable for read operations such as
:meth:`~SodaOperation.getCursor()` and
:meth:`~SodaOperation.getDocuments()`. For write operations, any value set
using this method is ignored.
As a convenience, the SodaOperation object is returned so that further
criteria can be specified by chaining methods together.
.. versionadded:: 7.0
.. method:: SodaOperation.version(value)
Specifies that documents with the specified version should be returned.
Typically this is used with :meth:`~SodaOperation.key()` to implement
optimistic locking, so that the write operation called later does not
affect a document that someone else has modified.
As a convenience, the SodaOperation object is returned so that further
criteria can be specified by chaining methods together.
.. versionadded:: 7.0

118
doc/src/sodacoll.rst
View File

@ -1,118 +0,0 @@
.. _sodacoll:
**********************
SODA Collection Object
**********************
.. note::
This object is an extension the DB API. It is used to represent SODA
collections and is created by methods
:meth:`SodaDatabase.createCollection()` and
:meth:`SodaDatabase.openCollection()`.
SODA support in cx_Oracle is in Preview status and should not be used in
production. It will be supported with a future version of Oracle Client
libraries.
.. method:: SodaCollection.createIndex(spec)
Creates an index on a SODA collection. The spec is expected to be a
dictionary or a JSON-encoded string. See this `overview
<https://www.oracle.com/pls/topic/
lookup?ctx=dblatest&id=GUID-4848E6A0-58A7-44FD-8D6D-A033D0CCF9CB>`__
for information on indexes in SODA.
Note that a commit should be performed before attempting to create an
index.
.. versionadded:: 7.0
.. method:: SodaCollection.drop()
Drops the collection from the database, if it exists. Note that if the
collection was created with mapMode set to True the underlying table will
not be dropped.
A boolean value is returned indicating if the collection was actually
dropped.
.. versionadded:: 7.0
.. method:: SodaCollection.dropIndex(name, force=False)
Drops the index with the specified name, if it exists.
The force parameter, if set to True, can be used to force the dropping of
an index that the underlying Oracle Database domain index doesn't normally
permit. This is only applicable to spatial and JSON search indexes.
See `here <https://www.oracle.com/pls/topic/
lookup?ctx=dblatest&id=GUID-F60F75DF-2866-4F93-BB7F-8FCE64BF67B6>`__
for more information.
A boolean value is returned indicating if the index was actually dropped.
.. versionadded:: 7.0
.. method:: SodaCollection.find()
This method is used to begin an operation that will act upon documents in
the collection. It creates and returns a
:ref:`SodaOperation object <sodaop>` which is used to specify the criteria
and the operation that will be performed on the documents that match that
criteria.
.. versionadded:: 7.0
.. method:: SodaCollection.getDataGuide()
Returns a :ref:`SODA document object <sodadoc>` containing property names,
data types and lengths inferred from the JSON documents in the collection.
It can be useful for exploring the schema of a collection. Note that this
method is only supported for JSON-only collections where a JSON search
index has been created with the 'dataguide' option enabled. If there are
no documents in the collection, None is returned.
.. versionadded:: 7.0
.. method:: SodaCollection.insertOne(doc)
Inserts a given document into the collection. The input document can be a
dictionary or list or an existing :ref:`SODA document object <sodadoc>`.
.. versionadded:: 7.0
.. method:: SodaCollection.insertOneAndGet(doc)
Similarly to :meth:`~SodaCollection.insertOne()` this method inserts a
given document into the collection. The only difference is that it
returns a :ref:`SODA Document object <sodadoc>`. Note that for performance
reasons the returned document does not contain the content.
.. versionadded:: 7.0
.. attribute:: SodaCollection.metadata
This read-only attribute returns a dicationary containing the metadata that
was used to create the collection. See this `collection metadata reference
<https://www.oracle.com/pls/topic/
lookup?ctx=dblatest&id=GUID-49EFF3D3-9FAB-4DA6-BDE2-2650383566A3>`__
for more information.
.. versionadded:: 7.0
.. attribute:: SodaCollection.name
This read-only attribute returns the name of the collection.
.. versionadded:: 7.0

90
doc/src/sodadb.rst
View File

@ -1,90 +0,0 @@
.. _sodadb:
********************
SODA Database Object
********************
.. note::
This object is an extension the DB API. It is returned by the method
:meth:`Connection.getSodaDatabase()`.
SODA support in cx_Oracle is in Preview status and should not be used in
production. It will be supported with a future version of Oracle Client
libraries.
.. method:: SodaDatabase.createCollection(name, metadata=None, mapMode=False)
Creates a SODA collection with the given name and returns a new
:ref:`SODA collection object <sodacoll>`. If you try to create a
collection, and a collection with the same name and metadata already
exists, then that existing collection is opened without error.
If metadata is specified, it is expected to be a string containing valid
JSON or a dictionary that will be transformed into a JSON string. This JSON
permits you to specify the configuration of the collection including
storage options; specifying the presence or absence of columns for creation
timestamp, last modified timestamp and version; whether the collection can
store only JSON documents; and methods of key and version generation. The
default metadata creates a collection that only supports JSON documents and
uses system generated keys. See this `collection metadata reference
<https://www.oracle.com/pls/topic/
lookup?ctx=dblatest&id=GUID-49EFF3D3-9FAB-4DA6-BDE2-2650383566A3>`__
for more information.
If the mapMode parameter is set to True, the new collection is mapped to an
existing table instead of creating a table. If a collection is created in
this way, dropping the collection will not drop the existing table either.
.. versionadded:: 7.0
.. method:: SodaDatabase.createDocument(content, key=None, mediaType="application/json")
Creates a :ref:`Soda document <sodadoc>` usable for SODA write operations.
You only need to use this method if your collection requires
client-assigned keys or has non-JSON content; otherwise, you can pass your
content directly to SODA write operations. SodaDocument attributes
'createdOn', 'lastModified' and 'version' will be None.
The content parameter can be a dictionary or list which will be transformed
into a JSON string and then UTF-8 encoded. It can also be a string which
will be UTF-8 encoded or it can be a bytes object which will be stored
unchanged. If a bytes object is provided and the content is expected to be
JSON, note that SODA only supports UTF-8, UTF-16LE and UTF-16BE encodings.
The key parameter should only be supplied if the collection in which the
document is to be placed requires client-assigned keys.
The mediaType parameter should only be supplied if the collection in which
the document is to be placed supports non-JSON documents and the content
for this document is non-JSON. Using a standard MIME type for this value is
recommended but any string will be accepted.
.. versionadded:: 7.0
.. method:: SodaDatabase.getCollectionNames(startName=None, limit=0)
Returns a list of the names of collections in the database that match the
criteria, in alphabetical order.
If the startName parameter is specified, the list of names returned will
start with this value and also contain any names that fall after this value
in alphabetical order.
If the limit parameter is specified and is non-zero, the number of
collection names returned will be limited to this value.
.. versionadded:: 7.0
.. method:: SodaDatabase.openCollection(name)
Opens an existing collection with the given name and returns a new
:ref:`SODA collection object <sodacoll>`. If a collection with that name
does not exist, None is returned.
.. versionadded:: 7.0

97
doc/src/sodadoc.rst
View File

@ -1,97 +0,0 @@
.. _sodadoc:
********************
SODA Document Object
********************
.. note::
This object is an extension the DB API. It is returned by the methods
:meth:`SodaDatabase.createDocument()`,
:meth:`SodaOperation.getDocuments()` and
:meth:`SodaOperation.getOne()` as well as by iterating over
:ref:`SODA document cursors <sodadoccur>`.
SODA support in cx_Oracle is in Preview status and should not be used in
production. It will be supported with a future version of Oracle Client
libraries.
.. attribute:: SodaDoc.createdOn
This read-only attribute returns the creation time of the document in
`ISO 8601 <https://www.iso.org/iso-8601-date-and-time-format.html>`__
format. Documents created by :meth:`SodaDatabase.createDocument()` or
fetched from collections where this attribute is not stored will return
None.
.. versionadded:: 7.0
.. method:: SodaDoc.getContent()
Returns the content of the document as a dictionary or list. This method
assumes that the content is application/json and will raise an exception if
this is not the case. If there is no content, however, None will be
returned.
.. versionadded:: 7.0
.. method:: SodaDoc.getContentAsBytes()
Returns the content of the document as a bytes object. If there is no
content, however, None will be returned.
.. versionadded:: 7.0
.. method:: SodaDoc.getContentAsString()
Returns the content of the document as a string. This method assumes that
the content is application/json and will raise an exception if this is not
the case. If there is no content, however, None will be returned.
.. versionadded:: 7.0
.. attribute:: SodaDoc.key
This read-only attribute returns the unique key assigned to this document.
Documents created by :meth:`SodaDatabase.createDocument()` may not have a
value assigned to them and return None.
.. versionadded:: 7.0
.. attribute:: SodaDoc.lastModified
This read-only attribute returns the last modified time of the document in
`ISO 8601 <https://www.iso.org/iso-8601-date-and-time-format.html>`__
format. Documents created by :meth:`SodaDatabase.createDocument()` or
fetched from collections where this attribute is not stored will return
None.
.. versionadded:: 7.0
.. attribute:: SodaDoc.mediaType
This read-only attribute returns the media type assigned to the document.
By convention this is expected to be a MIME type but no checks are
performed on this value. If a value is not specified when calling
:meth:`SodaDatabase.createDocument()` or the document is fetched from a
collection where this component is not stored, the string
"application/json" is returned.
.. versionadded:: 7.0
.. attribute:: SodaDoc.version
This read-only attribute returns the version assigned to this document.
Documents created by :meth:`SodaDatabase.createDocument()` or fetched
from collections where this attribute is not stored will return None.
.. versionadded:: 7.0

25
doc/src/sodadoccur.rst
View File

@ -1,25 +0,0 @@
.. _sodadoccur:
***************************
SODA Document Cursor Object
***************************
.. note::
This object is an extension the DB API. It is returned by the method
:meth:`SodaOperation.getCursor()` and implements the iterator protocol.
Each iteration will return a :ref:`SODA document object <sodadoc>`.
SODA support in cx_Oracle is in Preview status and should not be used in
production. It will be supported with a future version of Oracle Client
libraries.
.. method:: SodaDocCursor.close()
Close the cursor now, rather than whenever __del__ is called. The cursor
will be unusable from this point forward; an Error exception will be raised
if any operation is attempted with the cursor.
.. versionadded:: 7.0

165
doc/src/sodaop.rst
View File

@ -1,165 +0,0 @@
.. _sodaop:
*********************
SODA Operation Object
*********************
.. note::
This object is an extension the DB API. It represents an operation that
will be performed on all or some of the documents in a SODA collection. It
is created by the method :meth:`SodaCollection.find()`.
SODA support in cx_Oracle is in Preview status and should not be used in
production. It will be supported with a future version of Oracle Client
libraries.
.. method:: SodaOperation.count()
Returns a count of the number of documents in the collection that match
the criteria. If :meth:`~SodaOperation.skip()` or
:meth:`~SodaOperation.limit()` were called on this object, an exception is
raised.
.. versionadded:: 7.0
.. method:: SodaOperation.filter(value)
Sets a filter specification for complex document queries and ordering of
JSON documents. Filter specifications must be provided as a dictionary or
JSON-encoded string and can include comparisons, regular expressions,
logical and spatial operators, among others. See the
`overview of SODA filter specifications
<https://www.oracle.com/pls/topic/
lookup?ctx=dblatest&id=GUID-CB09C4E3-BBB1-40DC-88A8-8417821B0FBE>`__
for more information.
As a convenience, the SodaOperation object is returned so that further
criteria can be specified by chaining methods together.
.. versionadded:: 7.0
.. method:: SodaOperation.getCursor()
Returns a :ref:`SODA Document Cursor object <sodadoccur>` that can be used
to iterate over the documents that match the criteria.
.. versionadded:: 7.0
.. method:: SodaOperation.getDocuments()
Returns a list of :ref:`SODA Document objects <sodadoc>` that match the
criteria.
.. versionadded:: 7.0
.. method:: SodaOperation.getOne()
Returns a single :ref:`SODA Document object <sodadoc>` that matches the
criteria. Note that if multiple documents match the criteria only the first
one is returned.
.. versionadded:: 7.0
.. method:: SodaOperation.key(value)
Specifies that the document with the specified key should be returned.
This causes any previous calls made to this method and
:meth:`~SodaOperation.keys()` to be ignored.
As a convenience, the SodaOperation object is returned so that further
criteria can be specified by chaining methods together.
.. versionadded:: 7.0
.. method:: SodaOperation.keys(seq)
Specifies that documents that match the keys found in the supplied sequence
should be returned. This causes any previous calls made to this method and
:meth:`~SodaOperation.key()` to be ignored.
As a convenience, the SodaOperation object is returned so that further
criteria can be specified by chaining methods together.
.. versionadded:: 7.0
.. method:: SodaOperation.limit(value)
Specifies that only the specified number of documents should be returned.
This method is only usable for read operations such as
:meth:`~SodaOperation.getCursor()` and
:meth:`~SodaOperation.getDocuments()`. For write operations, any value set
using this method is ignored.
As a convenience, the SodaOperation object is returned so that further
criteria can be specified by chaining methods together.
.. versionadded:: 7.0
.. method:: SodaOperation.remove()
Removes all of the documents in the collection that match the criteria. The
number of documents that have been removed is returned.
.. versionadded:: 7.0
.. method:: SodaOperation.replaceOne(doc)
Replaces a single document in the collection with the specified document.
The input document can be a dictionary or list or an existing
:ref:`SODA document object <sodadoc>`. A boolean indicating if a document
was replaced or not is returned.
Currently the method :meth:`~SodaOperation.key()` must be called before
this method can be called.
.. versionadded:: 7.0
.. method:: SodaOperation.replaceOneAndGet(doc)
Similarly to :meth:`~SodaOperation.replaceOne()`, this method replaces a
single document in the collection with the specified document. The only
difference is that it returns a :ref:`SODA document object <sodadoc>`.
Note that for performance reasons the returned document does not contain
the content.
.. versionadded:: 7.0
.. method:: SodaOperation.skip(value)
Specifies the number of documents that match the other criteria that will
be skipped. This method is only usable for read operations such as
:meth:`~SodaOperation.getCursor()` and
:meth:`~SodaOperation.getDocuments()`. For write operations, any value set
using this method is ignored.
As a convenience, the SodaOperation object is returned so that further
criteria can be specified by chaining methods together.
.. versionadded:: 7.0
.. method:: SodaOperation.version(value)
Specifies that documents with the specified version should be returned.
Typically this is used with :meth:`~SodaOperation.key()` to implement
optimistic locking, so that the write operation called later does not
affect a document that someone else has modified.
As a convenience, the SodaOperation object is returned so that further
criteria can be specified by chaining methods together.
.. versionadded:: 7.0