PutRequest¶

class borneo.PutRequest[source]¶

Bases: WriteRequest

Represents the input to a NoSQLHandle.put() operation.

This request can be used to perform unconditional and conditional puts:

Overwrite any existing row. This is the default.

Succeed only if the row does not exist. Use PutOption.IF_ABSENT for this case.

Succeed only if the row exists. Use PutOption.IF_PRESENT for this case.

Succeed only if the row exists and its Version matches a specific Version. Use PutOption.IF_VERSION for this case and set_match_version() to specify the version to match.

Information about the existing row can be optionally returned if set_return_row() is set to true and one of the following occurs:

PutOption.IF_ABSENT is used and the operation fails because the row already exists.

PutOption.IF_VERSION is used and the operation fails because the row exists and its version does not match.

PutOption.IF_PRESENT is used and the operation succeeds provided that the server supports providing the existing row.

Requesting this information incurs additional cost and may affect operation latency.

On a successful operation the Version returned by PutResult.get_version() is non-none. Additional information, such as previous row information, may be available in PutResult.

The table name and value are required parameters.

Methods Summary

`get_compartment`()	Get the compartment id or name if set for the request.
`get_durability`()	Gets the durability to use for the operation or None if not set
`get_exact_match`()	Returns whether the value must be an exact match to the table schema or not.
`get_identity_cache_size`()	Gets the number of generated identity values that are requested from the server during a put if set in this request.
`get_match_version`()	Returns the `Version` used for a match on a conditional put.
`get_option`()	Returns the option specified for the put.
`get_return_row`()	Returns whether information about the exist row should be returned.
`get_table_name`()	Returns the table name to use for the operation.
`get_timeout`()	Returns the timeout to use for the operation, in milliseconds.
`get_ttl`()	Returns the `TimeToLive` value, if set.
`get_update_ttl`()	Returns True if the operation should update the ttl.
`get_use_table_default_ttl`()	Returns whether or not to update the row's time to live (TTL) based on a table default value if the row exists.
`get_value`()	Returns the value of the row to be used.
`set_compartment`(compartment)	Sets the name or id of a compartment to be used for this operation.
`set_durability`(durability)	Sets the durability to use for the operation.
`set_exact_match`(exact_match)	If True the value must be an exact match for the table schema or the operation will fail.
`set_identity_cache_size`(identity_cache_size)	Sets the number of generated identity values that are requested from the server during a put.
`set_match_version`(version)	Sets the `Version` to use for a conditional put operation.
`set_option`(option)	Sets the option for the put.
`set_return_row`(return_row)	Sets whether information about the exist row should be returned.
`set_table_name`(table_name)	Sets the table name to use for the operation.
`set_timeout`(timeout_ms)	Sets the request timeout value, in milliseconds.
`set_ttl`(ttl)	Sets the `TimeToLive` value, causing the time to live on the row to be set to the specified value on put.
`set_use_table_default_ttl`(update_ttl)	If value is True, and there is an existing row, causes the operation to update the time to live (TTL) value of the row based on the Table's default TTL if set.
`set_value`(value)	Sets the value to use for the put operation.
`set_value_from_json`(json_value)	Sets the value to use for the put operation based on a JSON string.

Methods Documentation

get_compartment()¶

Get the compartment id or name if set for the request.

Cloud service only.

Returns:: compartment id or name if set for the request, otherwise None if not set.
Return type:: str

get_durability()[source]¶

Gets the durability to use for the operation or None if not set

On-premises only

Returns:: the Durability
Versionadded::: 5.3.0

get_match_version()[source]¶

Returns the Version used for a match on a conditional put.

Returns:: the Version or None if not set.
Return type:: Version

get_option()[source]¶

Returns the option specified for the put.

Returns:: the option specified.
Return type:: PutOption

get_return_row()[source]¶

Returns whether information about the exist row should be returned.

Returns:: True if information should be returned.
Return type:: bool

get_table_name()¶

Returns the table name to use for the operation.

Returns:: the table name, or None if not set.
Returns:: str

get_timeout()[source]¶

Returns the timeout to use for the operation, in milliseconds. A value of 0 indicates that the timeout has not been set.

Returns:: the timeout value.
Return type:: int

get_ttl()[source]¶

Returns the TimeToLive value, if set.

Returns:: the TimeToLive if set, None otherwise.
Return type:: TimeToLive

get_update_ttl()[source]¶

Returns True if the operation should update the ttl.

Returns:: True if the operation should update the ttl.
Return type:: bool

get_use_table_default_ttl()[source]¶

Returns whether or not to update the row’s time to live (TTL) based on a table default value if the row exists. By default updates of existing rows do not affect that row’s TTL.

Returns:: whether or not to update the row’s TTL based on a table default value if the row exists.
Return type:: bool

get_value()[source]¶

Returns the value of the row to be used.

Returns:: the value, or None if not set.
Return type:: dict

set_compartment(compartment)[source]¶

Sets the name or id of a compartment to be used for this operation.

The compartment may be specified as either a name (or path for nested compartments) or as an id (OCID). A name (vs id) can only be used when authenticated using a specific user identity. It is not available if authenticated as an Instance Principal which can be done when calling the service from a compute instance in the Oracle Cloud Infrastructure. See borneo.iam.SignatureProvider.create_with_instance_principal().

Cloud service only.

Parameters:: compartment (str) – the compartment name or id. If using a nested compartment, specify the full compartment path compartmentA.compartmentB, but exclude the name of the root compartment (tenant).
Returns:: self.
Raises:: IllegalArgumentException – raises the exception if compartment is not a str.

set_durability(durability)[source]¶

Sets the durability to use for the operation.

On-premises only

Parameters:: durability (Durability) – the Durability to use
Returns:: self.
Raises:: IllegalArgumentException – raises the exception if Durability is not valid
Versionadded::: 5.3.0

set_match_version(version)[source]¶

Sets the Version to use for a conditional put operation. The Version is usually obtained from GetResult.get_version() or other method that returns a Version. When set, the put operation will succeed only if the row exists and its Version matches the one specified. This condition exists to allow an application to ensure that it is updating a row in an atomic read-modify-write cycle. Using this mechanism incurs additional cost.

Parameters:: version (Version) – the Version to match.
Returns:: self.
Raises:: IllegalArgumentException – raises the exception if version is not an instance of Version.

set_option(option)[source]¶

Sets the option for the put.

Parameters:: option (PutOption) – the option to set.
Returns:: self.

set_return_row(return_row)[source]¶

Sets whether information about the exist row should be returned. If set to true, information about the existing row will be returned if one of the following occurs:

PutOption.IF_ABSENT is used and the operation fails because the row already exists.

PutOption.IF_VERSION is used and the operation fails because the row exists and its version does not match.

PutOption.IF_PRESENT is used and the operation succeeds provided that the server supports providing the existing row.

Requesting this information incurs additional cost and may affect operation latency.

Parameters:: return_row (bool) – set to True if information should be returned.
Returns:: self.
Raises:: IllegalArgumentException – raises the exception if return_row is not True or False.

set_table_name(table_name)[source]¶

Sets the table name to use for the operation.

Parameters:: table_name (str) – the table name.
Returns:: self.
Raises:: IllegalArgumentException – raises the exception if table_name is not a string.

set_timeout(timeout_ms)[source]¶

Sets the request timeout value, in milliseconds. This overrides any default value set in NoSQLHandleConfig. The value must be positive.

Parameters:: timeout_ms (int) – the timeout value, in milliseconds.
Returns:: self.
Raises:: IllegalArgumentException – raises the exception if the timeout value is less than or equal to 0.

set_ttl(ttl)[source]¶

Sets the TimeToLive value, causing the time to live on the row to be set to the specified value on put. This value overrides any default time to live setting on the table.

Parameters:: ttl (TimeToLive) – the time to live.
Returns:: self.
Raises:: IllegalArgumentException – raises the exception if ttl is not an instance of TimeToLive.

set_use_table_default_ttl(update_ttl)[source]¶

If value is True, and there is an existing row, causes the operation to update the time to live (TTL) value of the row based on the Table’s default TTL if set. If the table has no default TTL this state has no effect. By default updating an existing row has no effect on its TTL.

Parameters:: update_ttl (bool) – True or False.
Returns:: self.
Raises:: IllegalArgumentException – raises the exception if update_ttl is not True or False.

set_value(value)[source]¶

Sets the value to use for the put operation. This is a required parameter and must be set using this method or set_value_from_json()

Parameters:: value (dict) – the row value.
Returns:: self.
Raises:: IllegalArgumentException – raises the exception if value is not a dictionary.

set_value_from_json(json_value)[source]¶

Sets the value to use for the put operation based on a JSON string. The string is parsed for validity and stored internally as a dict. This is a required parameter and must be set using this method or set_value()

Parameters:: json_value (str) – the row value as a JSON string.
Returns:: self.
Raises:: IllegalArgumentException – raises the exception if json_value is not a string.