4 SODA for REST HTTP Operations
The SODA for REST HTTP operations are described.
- SODA for REST HTTP Operation URIs
A SODA for REST HTTP operation is specified by a Universal Resource Identifier (URI). - SODA for REST HTTP Operation Response Bodies
If a SODA for REST HTTP operation returns information or objects, it does so in a response body. - GET catalog
GET
catalog gets all of the collection names for a given database schema (user account), along with information about each collection. - GET user collections
GET
user collections gets all or a subset of the collection names for a given database schema (user account). - GET JSON schema for collection
This operation gets a JSON schema that describes the structure and type information of the JSON documents in a given collection. - GET actions
GET
actions gets all of the available custom actions. - GET collection
GET
collection gets all or a subset of objects from a collection, using parameters to specify the subset. You can page through the set of returned objects. - GET object
GET
object gets a specified object from a specified collection. - DELETE collection
DELETE
collection deletes a collection. - DELETE object
DELETE
object deletes a specified object from a specified collection. - PATCH JSON document
PATCH
JSON document replaces a specified object with an patched (edited) copy of it. - POST object
POST
object inserts an uploaded object into a specified collection, assigning and returning its key. The collection must use server-assigned keys. - POST query
POST
query gets all or a subset of objects from a collection, using a filter. - POST bulk insert
POST
bulk insert inserts an array of objects into a specified collection, assigning and returning their keys. - POST bulk delete
POST
bulk delete deletes all or a subset of objects from a specified collection, using a filter to specify the subset. - POST bulk update (patch)
ThePOST
bulk update operation updates (patches) the objects of a specified collection. - POST index
POST
index creates indexes on the documents in a specified collection. - POST unindex
POST
unindex deletes indexes on objects in a specified collection. - PUT collection
PUT
collection creates a collection if it does not exist. - PUT object
PUT
object replaces a specified object in a specified collection with an uploaded object (typically a new version). If the collection has client-assigned keys and the uploaded object is not already in the collection, thenPUT
inserts the uploaded object into the collection.
4.1 SODA for REST HTTP Operation URIs
A SODA for REST HTTP operation is specified by a Universal Resource Identifier (URI).
The URI has any of these forms:
/ords/database-schema/soda/[version/[metadata-catalog/[collection]]]
/ords/database-schema/soda/[version/[custom-actions/action/[collection/[key]]]]
/ords/database-schema/soda/[version/[collection/[{key|?action=action}]]]
where:
-
ords
is the directory of the Oracle REST Data Services (ORDS) listener, of which SODA for REST is a component. -
database-schema
is the name of an Oracle Database schema (user account) that has been configured as an end point for SODA for REST. -
soda
is the name given to the Oracle Database JSON service when mapped as a template within ORDS. -
version
is the version number ofsoda
. -
custom-actions
is the name for the set of possible SODA actions. -
metadata-catalog
is the name for the catalog of SODA collections. -
collection
is the name of a collection (set) of objects stored indatabase-schema
. -
key
is a string that uniquely identifies (specifies) an object incollection
. -
action
is eitherquery
,index
,unindex
,insert
,update
,delete
, ortruncate
.
Note:
In the SODA for REST
URI syntax, after the version component, you can use
custom-actions
, metadata-catalog
, or a
particular collection name. When you use custom-actions
or
metadata-catalog
, the next segment in the URI, if there
is one, is a collection name.
Because of this syntax
flexibility, you cannot have a collection named either
custom-actions
or metadata-catalog
. An error
is raised if you try to create a collection with either of those names using SODA
for REST.
In other SODA implementations, besides SODA for REST,
nothing prevents you from creating and using a collection named
custom-actions
or metadata-catalog
. But for
possible interoperability, best practice calls for not using these names for
collections.
These two syntax possibilities are equivalent:
/ords/database-schema/soda/version/custom-actions/action/collection/
/ords/database-schema/soda/version/collection/?action=action
Actions can only be used with a POST
HTTP operation. (This applies to both URI syntaxes for performing actions.)
For some SODA for REST operations the path component of the URI syntax can be followed by an optional query component, which is preceded by a question mark (?
). The query component is composed of one or more parameter–value pairs separated by ampersand (&
) query delimiters.
In this URI, for example, the query component (?action=insert
) is composed of the single parameter–value pair action=insert
:
/ords/myUser/soda/v1.0/MyCollection/?action=insert
And in this URI, the query component is composed of two parameter–value pairs, fromID=MyCollection
and limit=2
:
/ords/myUser/soda/v1.0/metadata-catalog/?fromID=MyCollection&limit=2
Parent topic: SODA for REST HTTP Operations
4.2 SODA for REST HTTP Operation Response Bodies
If a SODA for REST HTTP operation returns information or objects, it does so in a response body.
For operation GET object, the response body is a single object.
Table 4-1 lists and describes fields that can appear in response bodies.
Table 4-1 Fields That Can Appear in Response Bodies
Field | Description |
---|---|
|
String that uniquely identifies an object (typically a JSON document) in a collection. |
|
HTTP entity tag (ETag)—checksum or version. |
|
Created-on time stamp. |
|
Last-modified time stamp. |
|
Object contents (applies only to JSON object). |
|
HTTP Content-Type (applies only to non-JSON object). |
|
HTTP Content-Length (applies only to non-JSON object). |
|
List of one or more collections or objects that the operation found or created. This field can be followed by the fields in Table 4-2. |
If an operation creates or returns objects, then its response body can have the additional fields in Table 4-2. The additional fields appear after field items
.
Table 4-2 Additional Response Body Fields for Operations that Return Objects
Field | Description |
---|---|
|
Name of collection. This field appears only in the response body of GET user collections. |
|
Properties of collection. This field appears only in the response body of GET user collections. |
|
|
|
Server-imposed maximum collection (row) limit. |
|
Offset of first object returned (if known). |
|
Number of objects returned. This is the only field that can appear in the response body of POST bulk delete. |
|
Number of objects in collection (if requested) |
|
Possible final field for |
Example 4-1 Response Body
This example shows the structure of a response body that returns 25 objects. The first object is a JSON object and the second is a jpeg
image. The collection that contains these objects contains additional objects.
{ "items" : [ { "id" : "key_of_object_1",
"etag" : "etag_of_object_1",
"lastModified" : "lastmodified_timestamp_of_object_1",
"value" : { object_1 } },
{ "id" : "key_of_object_2",
"etag" : "etag_of_object_2",
"lastModified" : "lastmodified_timestamp_of_object_2",
"mediaType" : "image/jpeg",
"bytes" : 1234
},
... ],
"hasMore" : true,
"limit" : 100,
"offset" : 50,
"count" : 25
"links" : [ ... ] }
Related Topics
Parent topic: SODA for REST HTTP Operations
4.3 GET catalog
GET
catalog gets all of the collection names for a given database schema (user account), along with information about each collection.
This information includes links to collection descriptions and a link to a JSON schema that describes the structure and type information of the JSON documents in the collection.
Note:
The existence of a JSON schema requires the collection to have a JSON search index with data-guide support, which requires Oracle Database Release 12c (12.2.0.1) or later.
- URL Pattern for GET catalog
The URL pattern forGET
catalog is described. - Response Codes for GET catalog
The response codes for GET catalog are described.
Related Topics
Parent topic: SODA for REST HTTP Operations
4.3.1 URL Pattern for GET catalog
The URL pattern for GET
catalog is described.
/ords/database-schema/soda/version/metadata-catalog
Without parameters, operation GET
catalog gets catalog information for all collections in database-schema
.
You can include one or more parameter–value pairs at the end of the URL, preceded by a question mark (?) and separated by ampersand (&) query delimiters.
Parameter | Description |
---|---|
|
Limits number of collections to |
|
Starts getting with |
Parent topic: GET catalog
4.3.2 Response Codes for GET catalog
The response codes for GET catalog are described.
200
Success — response body contains names and properties of collections in database schema (user account), ordered by name. For example:
{ "items": [
{ "name" : "employees",
"properties" : { .. .},
"links" : [
{ "rel" : "describes",
"href" :
"http://host:port/.../database-schema/soda/version/employees" },
{ "rel" : "canonical",
"href" :
"http://host:port/.../database-schema/soda/version/metadata-catalog/employees",
"mediaType" : "application/json" },
{ "rel" : "alternate",
"href" :
"http:host:port/.../database-schema/soda/version/metadata-catalog/employees",
"mediaType":"application/schema+json" } ] },
{ "name" : "departments",
"properties" : { ... },
"links" : [ ... ] }
...
{ "name" : "regions",
"properties" : { ... },
"links" : [ ... ] } ],
"hasMore":false }
If hasMore
is true
, then to get the next batch of collection names specify fromID=
last_returned_collection
. (In the preceding example, last_returned_collection
is "regions"
).
400
Parameter value is not valid.
401
Access is not authorized.
Related Topics
Parent topic: GET catalog
4.4 GET user collections
GET
user collections gets all or a subset of the collection names for a given database schema (user account).
- URL Pattern for GET user collections
The URL pattern forGET
user collections is described. - Response Codes for GET user collections
The response codes for GET user collections are described.
Related Topics
Parent topic: SODA for REST HTTP Operations
4.4.1 URL Pattern for GET user collections
The URL pattern for GET
user collections is described.
/ords/database-schema/soda/version/
Without parameters, GET user collections gets all collection names in database-schema
.
You can include one or more parameter–value pairs at the end of the URL, preceded by a question mark (?) and separated by ampersand (&) query delimiters.
Parameter | Description |
---|---|
|
Limits number of listed collection names to |
|
Starts getting with |
Parent topic: GET user collections
4.4.2 Response Codes for GET user collections
The response codes for GET user collections are described.
200
Success — response body contains names and properties of collections in database schema (user account), ordered by name. For example:
{ "items" : [
{ "name" : "employees",
"properties" : {...} },
{ "name" : "departments",
"properties" : {...} },
...
{ "name" : "regions",
"properties" : {...} } ],
"hasMore" : false }
If hasMore
is true
, then to get the next batch of collection names specify fromID=
last_returned_collection
. (In the preceding example, last_returned_collection
is "regions"
).
400
Parameter value is not valid.
401
Access is not authorized.
404
The database schema (user) was not found.
Parent topic: GET user collections
4.5 GET JSON schema for collection
This operation gets a JSON schema that describes the structure and type information of the JSON documents in a given collection.
Note:
The existence of a JSON schema requires the collection to have a JSON search index with data-guide support, which requires Oracle Database Release 12c (12.2.0.1) or later.
Besides a JSON schema for the collection, the operation also returns the collection metadata, as the value of field properties
.
- URL Pattern for GET JSON schema for collection
The URL pattern for getting a JSON schema for a given collection is described. - Response Codes for GET JSON schema for collection
The response codes for getting a JSON schema for a given collection are described.
Parent topic: SODA for REST HTTP Operations
4.5.1 URL Pattern for GET JSON schema for collection
The URL pattern for getting a JSON schema for a given collection is described.
/ords/database-schema/soda/version/metadata-catalog/collection
No parameters.
Parent topic: GET JSON schema for collection
4.5.2 Response Codes for GET JSON schema for collection
The response codes for getting a JSON schema for a given collection are described.
200
Success. The response body contains a JSON schema for the collection, as the value of field schema
, and the collection metadata, as the value of field properties
.
For example:
{"name" : "employees",
"properties" : {
"schemaName" : "MYUSER",
"tableName" : "EMPLOYEES",
"keyColumn" : {"name" : "ID",
"sqlType" : "VARCHAR2",
"maxLength" : 24,
"path" : "_id",
"assignmentMethod" : "MONGO"},
"contentColumn" : {"name" : "DOCUMENT",
"sqlType" : "VARCHAR2",
"maxLength" : 4000,
"validation" : "STRICT"},
"versionColumn" : {"name" : "CHECKSUM",
"type" : "String",
"method" : "UUID"},
"lastModifiedColumn" : {"name" : "LAST_MODIFIED",
"index" : "PEOPLE_T1"},
"readOnly" : false},
"schema" : {
"type" : "object",
"properties" : {
"dob" : {"type" : "string",
"o:length" : 16,
"o:preferred_column_name" : "dob"},
"name" : {"type" : "string",
"o:length" : 16,
"o:preferred_column_name" : "name"},
"email" : {"type" : "array",
"o:length" : 64,
"o:preferred_column_name" : "email",
"items" : {
"type" : "string",
"o:length" : 32,
"o:preferred_column_name" : "scalar_string"}},
"empno" : {"type" : "number",
"o:length" : 8,
"o:preferred_column_name" : "empno"},
"title" : {"type" : "string",
"o:length" : 16,
"o:preferred_column_name" : "title"},
"salary" : {"type" : "number",
"o:length" : 8,
"o:preferred_column_name" : "salary"},
"spouse" : {"type" : "null",
"o:length" : 4,
"o:preferred_column_name" : "spouse"},
"address" : {"type" : "object",
"o:length" : 128,
"o:preferred_column_name" : "address",
"properties" : {
"city" : {"type" : "string",
"o:length" : 16,
"o:preferred_column_name" : "city"},
"state" : {"type" : "string",
"o:length" : 2,
"o:preferred_column_name" : "state"},
"street" : {"type" : "string",
"o:length" : 32,
"o:preferred_column_name" : "street"}}},
"company" : {"type" : "string",
"o:length" : 16,
"o:preferred_column_name" : "company"},
"location" : {"type" : "object",
"o:length" : 64,
"o:preferred_column_name" : "location",
"properties" : {
"type" : {
"type" : "string",
"o:length" : 8,
"o:preferred_column_name" : "type"},
"coordinates" : {
"type" : "array",
"o:length" : 32,
"o:preferred_column_name" : "coordinates",
"items" : {
"type" : "number",
"o:length" : 8,
"o:preferred_column_name" : "scalar_number"}}}},
"department" : {"type" : "string",
"o:length" : 16,
"o:preferred_column_name" : "department"}}},
"links" : [
{"rel" : "describes",
"href" :
"http : //host:port/.../database-schema/soda/version/employees"},
{"rel" : "canonical",
"href" :
"http : //host:port/.../database-schema/soda/version/metadata-catalog/employees",
"mediaType" : "application/json"},
{"rel" : "alternate",
"href" :
"http : //host:port/.../database-schema/soda/version/metadata-catalog/employees",
"mediaType" : "application/schema+json"}]}
401
Access is not authorized.
404
The collection does not exist.
Related Topics
Parent topic: GET JSON schema for collection
4.6 GET actions
GET
actions gets all of the available custom actions.
- URL Pattern for GET actions
The URL pattern forGET
actions is described.
Parent topic: SODA for REST HTTP Operations
4.6.1 URL Pattern for GET actions
The URL pattern for GET
actions is described.
/ords/database-schema/soda/version/custom-actions/
No parameters.
Parent topic: GET actions
4.7 GET collection
GET
collection gets all or a subset of objects from a collection, using parameters to specify the subset. You can page through the set of returned objects.
- URL Pattern for GET collection
The URL pattern forGET
collection is described. - Response Codes for GET collection
The response codes forGET
collection are described. - Links Array for GET collection
Thelinks
array forGET
collection is described.
Parent topic: SODA for REST HTTP Operations
4.7.1 URL Pattern for GET collection
The URL pattern for GET
collection is described.
/ords/database-schema/soda/version/collection/
Note:
For non-JSON objects in the collection, GET collection
returns, instead of document content, the media type and (if known) the size in bytes.
You can include one or more parameter–value pairs at the end of the URL, preceded by a question mark (?
) and separated by ampersand (&) query delimiters.
Parameter | Description |
---|---|
|
Limits number of objects returned to a maximum of |
|
Skips |
|
Gets only object Regardless of the |
|
Returns number of objects in collection. Note: Inefficient |
|
Starts getting objects after |
|
Stops getting objects before |
|
Starts getting objects after |
|
Stops getting objects before |
|
Gets only objects with a |
|
Gets only objects with a |
|
Equivalent to a |
Related Topics
Parent topic: GET collection
4.7.2 Response Codes for GET collection
The response codes for GET
collection are described.
200
Success—response body contains the specified objects from collection
(or only their keys, if you specified fields=id
). For example:
{ "items" : [
{ "id" : "key_of_object_1",
"etag" : "etag_of_object_1",
"lastModified" : "lastmodified_timestamp_of_object_1",
"value" : { object_1 } },
{ "id" : "key_of_object_2",
"etag" : "etag_of_object_2",
"lastModified" : "lastmodified_timestamp_of_object_2",
"value" : { object_2 } },
{ "id" : "key_of_object_3",
"etag" : "etag_of_object_3",
"lastModified" : "lastmodified_timestamp_of_object_3",
"mediaType" : "image/jpeg",
"bytes" : 1234 },
... ],
"hasMore" : true,
"limit" : 100,
"offset" : 50,
"count" : 25
"links" : [ ... ] }
If hasMore
is true
, then to get the next batch of objects repeat the operation with an appropriate parameter. For example:
-
offset=
n
if the response body includes the offset -
toID=
last_returned_key
orbefore=
last_returned_key
if the response body includesdescending=true
-
fromID=
last_returned_key
orafter=
last_returned_key
if the response body does not includedescending=true
400
Parameter value is not valid.
401
Access is not authorized.
404
Collection was not found.
Related Topics
Parent topic: GET collection
4.7.3 Links Array for GET collection
The links
array for GET
collection is described.
The existence and content of the links
array depends on the mode of the GET collection
operation, which is determined by its parameters.
When the links
array exists, it has an element for each returned object. Each element contains links from that object to other objects. The possible links are:
-
first
, which links the object to the first object in the collection -
prev
, which links the object to the previous object in the collection -
next
, which links the object to the next object in the collection
Using prev
and next
links, you can page through the set of returned objects.
Table 4-3 shows how GET collection
parameters determine mode and the existence and content of the links
array.
Table 4-3 Relationship of GET collection Parameters to Mode and Links Array
Parameter | Mode | Links Array |
---|---|---|
|
Keys-only |
Does not exist (regardless of other parameters). |
|
Offset |
Has an element for each returned object. Each element has these links, except as noted:
|
|
Keyed |
Has an element for each returned object. Each element has these links, except as noted:
|
|
|
Does not exist. |
|
Query |
Does not exist. |
Related Topics
Parent topic: GET collection
4.8 GET object
GET
object gets a specified object from a specified collection.
- URL Pattern for GET object
The URL pattern forGET
object is described. - Request Headers for GET object
The request headers forGET
object are described. - Response Codes for GET object
The response codes forGET
object are described.
Related Topics
Parent topic: SODA for REST HTTP Operations
4.8.1 URL Pattern for GET object
The URL pattern for GET
object is described.
/ords/database-schema/soda/version/collection/key
Parent topic: GET object
4.8.2 Request Headers for GET object
The request headers for GET
object are
described.
Operation GET object
accepts these
optional request
headers:
Header | Description |
---|---|
|
Returns response code 304 if object has not changed since |
|
Returns response code 304 if the etag (object version) value you set in the header matches the etag value of the document. |
Parent topic: GET object
4.8.3 Response Codes for GET object
The response codes for GET
object are described.
200
Success—response body contains object identified by the URL pattern.
204
Object content is null.
304
The object was not modified.
401
Access is not authorized.
404
Collection or object was not found.
Related Topics
Parent topic: GET object
4.9 DELETE collection
DELETE
collection deletes a collection.
To delete all objects from a collection, but not delete the collection itself, use POST bulk delete.
- URL Pattern for DELETE collection
The URL pattern forDELETE
collection is described. - Response Codes for DELETE collection
The response codes forDELETE
collection are described.
Related Topics
Parent topic: SODA for REST HTTP Operations
4.9.1 URL Pattern for DELETE collection
The URL pattern for DELETE
collection is described.
/ords/database-schema/soda/version/collection/
No parameters.
Parent topic: DELETE collection
4.9.2 Response Codes for DELETE collection
The response codes for DELETE
collection are described.
200
Success—collection was deleted.
401
Access is not authorized.
404
Collection was not found.
Related Topics
Parent topic: DELETE collection
4.10 DELETE object
DELETE
object deletes a specified object from a specified collection.
- URL Pattern for DELETE object
The URL pattern forDELETE
object is described. - Response Codes for DELETE object
The response codes forDELETE
object are described.
Related Topics
Parent topic: SODA for REST HTTP Operations
4.10.1 URL Pattern for DELETE object
The URL pattern for DELETE
object is described.
/ords/database-schema/soda/version/collection/key
No parameters.
Parent topic: DELETE object
4.10.2 Response Codes for DELETE object
The response codes for DELETE
object are described.
200
Success—object was deleted.
401
Access is not authorized.
404
Collection or bject was not found.
405
Collection is read-only.
Related Topics
Parent topic: DELETE object
4.11 PATCH JSON document
PATCH
JSON document replaces a specified object with an patched (edited) copy of it.
Note:
To use operation PATCH
JSON document you need Oracle Database Release 18c or later.
- URL Pattern for PATCH JSON document
The URL pattern forPATCH
JSON document is described. - Request Headers for PATCH JSON document
Use headerContent-Type=application/json-patch+json
for operationPATCH
JSON document. - Request Body for PATCH JSON document
The request body forPATCH
JSON document contains a JSON Patch specification, that is, an array of objects, each of which specifies a JSON Patch step (operation). The operations are performed successively in array order. - Response Codes for PATCH JSON Document
The response codes forPATCH
JSON document are described.
Related Topics
Parent topic: SODA for REST HTTP Operations
4.11.1 URL Pattern for PATCH JSON document
The URL pattern for PATCH
JSON document is described.
/ords/database-schema/soda/version/collection/key
No parameters.
Parent topic: PATCH JSON document
4.11.2 Request Headers for PATCH JSON document
Use header Content-Type=application/json-patch+json
for operation PATCH
JSON document.
Parent topic: PATCH JSON document
4.11.3 Request Body for PATCH JSON document
The request body for PATCH
JSON document contains a JSON Patch specification, that is, an array of objects, each of which specifies a JSON Patch step (operation). The operations are performed successively in array order.
The syntax and meaning of a JSON Patch specification, which describes changes to a JSON document, are specified in the JSON Patch standard, RFC 6902. Paths to parts of a JSON document that are referenced in a JSON Patch specification are specified using the JSON Pointer standard, RFC 6901.
See Also:
-
JSON Pointer (RFC 6901) for information about JSON Pointer paths
Parent topic: PATCH JSON document
4.11.4 Response Codes for PATCH JSON Document
The response codes for PATCH
JSON document are described.
200
Success — document was patched (updated).
401
Access is not authorized.
404
Document or collection not found.
405
Collection is read-only.
Related Topics
Parent topic: PATCH JSON document
4.12 POST object
POST
object inserts an uploaded object into a specified collection, assigning and returning its key. The collection must use server-assigned keys.
If the collection uses client-assigned keys, use PUT object.
- URL Pattern for POST object
The URL pattern forPOST
object is described. - Request Body for POST object
The request body forPOST
object is the uploaded object to be inserted in the collection. - Response Codes for POST object
The response codes forPOST
object are described.
Parent topic: SODA for REST HTTP Operations
4.12.1 URL Pattern for POST object
The URL pattern for POST
object is described.
/ords/database-schema/soda/version/collection/
No parameters.
Parent topic: POST object
4.12.2 Request Body for POST object
The request body for POST
object is the uploaded object to be inserted in the collection.
Parent topic: POST object
4.12.3 Response Codes for POST object
The response codes for POST
object are described.
201
Success — object is in collection; response body contains server-assigned key and possibly other information. For example:
{ "items" : [ { "id" : "key",
"etag" : "etag",
"lastModified" : "last_modified_timestamp"
"created" : "created_timestamp" } ],
"hasMore" : false }
202
Object was accepted and queued for asynchronous insertion; response body contains server-assigned key.
401
Access is not authorized.
405
Collection is read-only.
501
Unsupported operation (for example, no server-side key assignment).
Related Topics
Parent topic: POST object
4.13 POST query
POST
query gets all or a subset of objects from a collection, using a filter.
A links
section is not returned for a POST
query operation, so you cannot directly do next and previous paging.
Note:
As an alternative to using POST query
with a filter in the request body you can use GET collection
, passing the same filter as the value of URL parameter q
. For example, these two commands are equivalent, where the content of file QBE.1.json
is { "User" : "TGATES" }
:
curl -X POST --data-binary @QBE.1.json -H "Content-Type: application/json" http://localhost:8080/ords/database-schema/soda/latest/custom-actions/query/MyCollection/
curl -X GET -H "Content-Type: application/json" http://localhost:8080/ords/database-schema/soda/latest/MyCollection/?q={%20%22User%22%20:%20%22TGATES%22%20}
- URL Pattern for POST query
The URL pattern forPOST
query is described. - Request Body for POST query
The request body for aPOST
query action is a QBE (a filter-specification). - Response Codes for POST query
The response codes forPOST
query are described.
Parent topic: SODA for REST HTTP Operations
4.13.1 URL Pattern for POST query
The URL pattern for POST
query is described.
Query a collection using a filter, with either of these URI patterns:
/ords/database-schema/soda/version/custom-actions/query/collection
/ords/database-schema/soda/version/collection?action=query
You can include one or more parameter–value pairs at the end of the URL, preceded by a question mark (?) and separated by ampersand (&) query delimiters. Parameters are optional, except as noted.
Parameter | Description |
---|---|
|
Required, if the second syntax form is used. Specifies that the kind of action is a query. |
|
Limit number of returned objects to |
|
Skip |
|
Return object |
Parent topic: POST query
4.13.2 Request Body for POST query
The request body for a POST
query action is a QBE (a filter-specification).
The request body cannot be empty, but it can be the empty object, {}
. If it is {}
then all objects in the collection are returned.
See Also:
Oracle Database Introduction to Simple Oracle Document Access (SODA) for information about SODA filter specifications.
Parent topic: POST query
4.13.3 Response Codes for POST query
The response codes for POST
query are described.
200
Success—object is in collection; response body contains all objects in collection that match filter.
401
Access is not authorized.
404
The collection was not found.
Related Topics
Parent topic: POST query
4.14 POST bulk insert
POST
bulk insert inserts an array of objects into a specified collection, assigning and returning their keys.
- URL Pattern for POST bulk insert
The URL pattern forPOST
bulk insert is described. - Request Body for POST bulk insert
The request body forPOST
bulk insert is an array of objects. - Response Codes for POST bulk insert
The response codes forPOST
bulk insert are described.
Parent topic: SODA for REST HTTP Operations
4.14.1 URL Pattern for POST bulk insert
The URL pattern for POST
bulk insert is described.
Insert one or more objects into a collection, using either of these URI patterns:
/ords/database-schema/soda/version/custom-actions/insert/collection
/ords/database-schema/soda/version/collection?action=insert
You can include one or more parameter–value pairs at the end of the URL, preceded by a question mark (?
) and separated by ampersand (&) query delimiters.
Parameter | Description |
---|---|
|
Required, if the second syntax form is used. Specifies that the kind of action is a bulk insert. |
Parent topic: POST bulk insert
4.14.2 Request Body for POST bulk insert
The request body for POST
bulk insert is an array of objects.
Parent topic: POST bulk insert
4.14.3 Response Codes for POST bulk insert
The response codes for POST
bulk insert are described.
200
Success — response body contains an array with the assigned keys for inserted objects. For example:
{ "items" : [ { "id" : "12345678",
"etag" : "...",
"lastModified" : "..."
"created" : "..." },
{ "id" : "23456789",
"etag" : "...",
"lastModified" : "..."
"created" : "..." } ],
"hasMore" : false }
401
Access is not authorized.
404
Collection was not found.
405
Collection is read-only.
Related Topics
Parent topic: POST bulk insert
4.15 POST bulk delete
POST
bulk delete deletes all or a subset of objects from a specified collection, using a filter to specify the subset.
Note:
If you delete all objects from a collection, the empty collection continues to exist. To delete the collection itself, use DELETE collection.
There are two bulk-delete operations, with the HTTP POST actions delete
and truncate
, respectively. Action delete
is more general; you can use it to delete some or all objects in a collection. Action truncate
always deletes all objects from the collection. Action delete
is driven by a filter, which selects the objects to delete.
- URL Pattern for POST bulk delete
The URL pattern forPOST
bulk delete is described. - Request Body for POST bulk delete (Optional)
- Response Codes for POST bulk delete
The response codes forPOST
bulk delete are described.
Related Topics
Parent topic: SODA for REST HTTP Operations
4.15.1 URL Pattern for POST bulk delete
The URL pattern for POST
bulk delete is described.
Delete some or all objects from a collection, as determined by a filter using either of these URI patterns:
/ords/database-schema/soda/version/custom-actions/delete/collection
/ords/database-schema/soda/version/collection?action=delete
Delete all objects from a collection (truncate the collection) using either of these URI patterns:
/ords/database-schema/soda/version/custom-actions/truncate/collection
/ords/database-schema/soda/version/collection?action=truncate
You can include one or more parameter–value pairs at the end of the URL, preceded by a question mark (?) and separated by ampersand (&) query delimiters.
Action | Description |
---|---|
|
Required. Specifies the deletion of all or a subset of objects from |
|
Required. Specifies the deletion of all objects from |
WARNING:
If you specify delete
as the action, and you use the empty object, {}
, as the filter specification, then the operation deletes all objects from the collection.
Parent topic: POST bulk delete
4.15.2 Request Body for POST bulk delete (Optional)
If the action is
delete
(not truncate
) then the request body
contains the filter (QBE) that specifies which documents to delete from the
collection.
See Also:
Oracle Database Introduction to Simple Oracle Document Access (SODA) for information about SODA filter specifications
Parent topic: POST bulk delete
4.15.3 Response Codes for POST bulk delete
The response codes for POST
bulk delete are described.
200
Success — response body contains the number of deleted objects, as the value of fields count
and itemsDeleted
. For example:
{ "count" : 42,
"itemsDeleted : 42 }
401
Access is not authorized.
404
Collection not found.
405
Collection is read-only.
Related Topics
Parent topic: POST bulk delete
4.16 POST bulk update (patch)
The POST
bulk update operation updates (patches) the objects of a specified collection.
Objects that match a QBE are patched according to a JSON Patch specification.
Note:
To use operation POST
bulk update you need Oracle Database Release 18c or later.
- URL Pattern for POST bulk update (patch)
The URL pattern forPOST
bulk update is described. - Request Body for POST bulk update (patch)
The request body forPOST
bulk update is an array of objects. - Response Codes for POST bulk update (patch)
The response codes forPOST
bulk update are described.
Parent topic: SODA for REST HTTP Operations
4.16.1 URL Pattern for POST bulk update (patch)
The URL pattern for POST
bulk update is described.
Update one or more objects of a collection, using either of these URI patterns:
/ords/database-schema/soda/version/custom-actions/update/collection
/ords/database-schema/soda/version/collection?action=update
You can include one or more parameter–value pairs at the end of the URL, preceded by a question mark (?) and separated by ampersand (&) query delimiters.
Parameter | Description |
---|---|
|
Required, if the second syntax form is used. Specifies that the kind of action is a bulk update. |
Parent topic: POST bulk update (patch)
4.16.2 Request Body for POST bulk update (patch)
The request body for POST
bulk update is an array of objects.
The request body is a QBE that has a $patch
field whose value is a JSON Patch specification, as in Example 3-10.
Parent topic: POST bulk update (patch)
4.16.3 Response Codes for POST bulk update (patch)
The response codes for POST
bulk update are described.
200
Success — response body contains the number of objects updated, as the value of fields count
and itemsUpdated
. For example:
{ "count" : 42,
"itemsUpdated : 42
401
Access is not authorized.
405
Not allowed: collection is read-only.
Related Topics
Parent topic: POST bulk update (patch)
4.17 POST index
POST
index creates indexes on the documents in a specified collection.
Note:
To create an index with SODA you need Oracle Database Release 12c (12.2.0.1) or later. But to create a B-tree index that for a DATE
or TIMESTAMP
value you need Oracle Database Release 18c (18.1) or later.
- URL Pattern for POST index
The URL pattern forPOST
index is described. - Request Body for POST index
The request body forPOST
index is a SODA index specification. - Response Codes for POST index
The response codes forPOST
index are described.
Parent topic: SODA for REST HTTP Operations
4.17.1 URL Pattern for POST index
The URL pattern for POST
index is described.
Index one or more objects of a collection, using either of these URI patterns:
/ords/database-schema/soda/version/custom-actions/index/collection
/ords/database-schema/soda/version/collection?action=index
You can include one or more parameter–value pairs at the end of the URL, preceded by a question mark (?) and separated by ampersand (&) query delimiters.
Parameter | Description |
---|---|
|
Required, if the second syntax form is used. Specifies that the action is an indexing action. |
Parent topic: POST index
4.17.2 Request Body for POST index
The request body for POST
index is a SODA index
specification.
A SODA index specification is a JSON object that specifies a particular kind of Oracle Database index, which is used for operations on JSON documents. You can specify these kinds of index:
-
B-tree: Used to index scalar JSON values.
-
Spatial: Used to index GeoJSON geographic data.
-
Search: Used for one or both of the following:
-
Ad hoc structural queries or full-text searches
-
JSON data guide
-
Note:
To create a data
guide-enabled JSON search index, or to data guide-enable an existing JSON search
index, you need database privilege CTXAPP
and Oracle Database
Release 12c (12.2.0.1) or later.
See Also:
-
Oracle Database Introduction to Simple Oracle Document Access (SODA) for an overview of using SODA indexing
-
Oracle Database Introduction to Simple Oracle Document Access (SODA) for information about SODA index specifications
Parent topic: POST index
4.17.3 Response Codes for POST index
The response codes for POST
index are described.
200
Success.
401
Access is not authorized.
404
Collection was not found.
Related Topics
Parent topic: POST index
4.18 POST unindex
POST
unindex deletes indexes on objects in a specified collection.
- URL Pattern for POST unindex
The URL pattern forPOST
unindex is described. - Request Body for POST unindex
The request body forPOST
unindex is a SODA index specification. But only the name of the index need be specified — the rest of the index specification is ignored. - Response Codes for POST unindex
The response codes forPOST
unindex are described.
Parent topic: SODA for REST HTTP Operations
4.18.1 URL Pattern for POST unindex
The URL pattern for POST
unindex is described.
Unindex one or more objects of a collection, using either of these URI patterns:
/ords/database-schema/soda/version/custom-actions/unindex/collection
/ords/database-schema/soda/version/collection?action=unindex
You can include one or more parameter–value pairs at the end of the URL, preceded by a question mark (?) and separated by ampersand (&) query delimiters.
Parameter | Description |
---|---|
|
Required, if the second syntax form is used. Specifies that the action is an unindexing action. |
Parent topic: POST unindex
4.18.2 Request Body for POST unindex
The request body for POST
unindex is a SODA index specification. But only the name of the index need be specified — the rest of the index specification is ignored.
See Also:
Oracle Database Introduction to Simple Oracle Document Access (SODA) for information about SODA index specifications
Parent topic: POST unindex
4.18.3 Response Codes for POST unindex
The response codes for POST
unindex are described.
200
Success.
401
Access is not authorized.
404
Collection was not found.
Related Topics
Parent topic: POST unindex
4.19 PUT collection
PUT
collection creates a collection if it does not exist.
- URL Pattern for PUT collection
The URL pattern forPUT
collection is described. - Request Body for PUT collection (Optional)
The request body forPUT
collection optionally contains a collection specification, which defines the metadata of the collection that is created. (If no specification is present then the default metadata is used.) - Response Codes for PUT collection
The response codes forPUT
collection are described.
Related Topics
Parent topic: SODA for REST HTTP Operations
4.19.1 URL Pattern for PUT collection
The URL pattern for PUT
collection is described.
/ords/database-schema/soda/version/collection
No parameters.
Parent topic: PUT collection
4.19.2 Request Body for PUT collection (Optional)
The request body for PUT
collection optionally contains a collection specification, which defines the metadata of the collection that is created. (If no specification is present then the default metadata is used.)
Parent topic: PUT collection
4.19.3 Response Codes for PUT collection
The response codes for PUT
collection are described.
200
Collection with the same name and properties already exists.
201
Success—collection was created.
401
Access is not authorized.
Related Topics
Parent topic: PUT collection
4.20 PUT object
PUT
object replaces a specified object in a specified collection with an uploaded object (typically a new version). If the collection has client-assigned keys and the uploaded object is not already in the collection, then PUT
inserts the uploaded object into the collection.
- URL Pattern for PUT object
The URL pattern forPUT
object is described. - Request Body for PUT object
The request body forPUT
object is the uploaded object. - Response Codes for PUT object
The response codes forPUT
object are described.
Related Topics
Parent topic: SODA for REST HTTP Operations
4.20.1 URL Pattern for PUT object
The URL pattern for PUT
object is described.
There are two forms of the URL pattern:
-
Pattern for a collection that has client-assigned keys:
/ords/database-schema/soda/version/collection/key
-
Pattern for a collection that has system-assigned keys:
/ords/database-schema/soda/version/collection/
No parameters.
Parent topic: PUT object
4.20.2 Request Body for PUT object
The request body for PUT
object is the uploaded object.
Parent topic: PUT object
4.20.3 Response Codes for PUT object
The response codes for PUT
object are described.
200
Success—object was replaced.
401
Access is not authorized.
405
Collection is read-only.
Related Topics
Parent topic: PUT object