Skip to main content

streams

Creates, updates, deletes, gets or lists a streams resource.

Overview​

Namestreams
TypeResource
Idoci.streaming.streams

Fields​

The following fields are returned by SELECT queries:

NameDatatypeDescription
idstringThe OCID of the stream. (example: ocid1.stream.realm.region.mnopqr789)
namestringThe name of the stream. Avoid entering confidential information. Example: TelemetryEvents (example: TelemetryEvents)
compartmentIdstringThe OCID of the stream. (example: ocid1.compinstance.realm.region.zxcvbn432765)
definedTagsobjectDefined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm). Example: `{"Operations": {"CostCenter": "42"}}'
freeformTagsobjectFree-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. Exists for cross-compatibility only. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm). Example: {"Department": "Finance"}
lifecycleStatestringThe current state of the stream. (CREATING, ACTIVE, DELETING, DELETED, FAILED, UPDATING)
lifecycleStateDetailsstringAny additional details about the current state of the stream.
messagesEndpointstringThe endpoint to use when creating the StreamClient to consume or publish messages in the stream. If the associated stream pool is private, the endpoint is also private and can only be accessed from inside the stream pool's associated subnet.
partitionsintegerThe number of partitions in the stream.
retentionInHoursintegerThe retention period of the stream, in hours. This property is read-only.
streamPoolIdstringThe OCID of the stream pool that contains the stream. (example: ocid1.streampool.realm.region.zxcvbn432765)
timeCreatedstring (date-time)The date and time the stream was created, expressed in in [RFC 3339](https:​//tools.ietf.org/rfc/rfc3339) timestamp format. Example: 2018-04-20T00:00:07.405Z

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
getselectstreamId, regionopc-request-idGets detailed information about a stream, including the number of partitions.
listselectregioncompartmentId, streamPoolId, id, name, limit, page, sortBy, sortOrder, lifecycleState, opc-request-idLists the streams in the given compartment id.<br />If the compartment id is specified, it will list streams in the compartment, regardless of their stream pool.<br />If the stream pool id is specified, the action will be scoped to that stream pool.<br />The compartment id and stream pool id cannot be specified at the same time.<br />
createinsertregion, name, partitionsopc-request-idStarts the provisioning of a new stream.<br />The stream will be created in the given compartment id or stream pool id, depending on which parameter is specified.<br />Compartment id and stream pool id cannot be specified at the same time.<br />To track the progress of the provisioning, you can periodically call [GetStream](#/en/streaming/20180418/Stream/GetStream).<br />In the response, the lifecycleState parameter of the [Stream](#/en/streaming/20180418/Stream/) object tells you its current state.<br />
updateupdatestreamId, regionopc-request-id, if-matchUpdates the stream. Only specified values will be updated.<br />
deletedeletestreamId, regionopc-request-id, if-matchDeletes a stream and its content. Stream contents are deleted immediately. The service retains records of the stream itself for 90 days after deletion.<br />The lifecycleState parameter of the Stream object changes to DELETING and the stream becomes inaccessible for read or write operations.<br />To verify that a stream has been deleted, make a [GetStream](#/en/streaming/20180418/Stream/GetStream) request. If the call returns the stream's<br />lifecycle state as DELETED, then the stream has been deleted. If the call returns a "404 Not Found" error, that means all records of the<br />stream have been deleted.<br />
change_compartmentexecstreamId, region, compartmentIdif-match, opc-request-idMoves a resource into a different compartment.<br />When provided, If-Match is checked against ETag values of the resource.<br />The stream will also be moved into the default stream pool in the destination compartment.<br />

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
regionstringOCI region identifier (e.g. us-ashburn-1, ap-sydney-1); resolves from OCI_REGION when not supplied in the query. (default: us-ashburn-1, x-stackQL-envVar: OCI_REGION)
streamIdstringThe OCID of the stream.
compartmentIdstringThe OCID of the compartment. Is exclusive with the streamPoolId parameter. One of them is required.
idstringA filter to return only resources that match the given ID exactly.
if-matchstringFor optimistic concurrency control. In the PUT or DELETE call for a resource, set the if-match parameter to the value of the etag from a previous GET or POST response for that resource. The resource will be updated or deleted only if the etag you provide matches the resource's current etag value.
lifecycleStatestringA filter to only return resources that match the given lifecycle state. The state value is case-insensitive.
limitintegerThe maximum number of items to return. The value must be between 1 and 50. The default is 10.
namestringA filter to return only resources that match the given name exactly.
opc-request-idstringThe unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.
pagestringThe page at which to start retrieving results.
sortBystringThe field to sort by. You can provide no more than one sort order. By default, TIMECREATED sorts results in descending order and NAME sorts results in ascending order.
sortOrderstringThe sort order to use, either 'asc' or 'desc'.
streamPoolIdstringThe OCID of the stream pool. Is exclusive with the compartmentId parameter. One of them is required.

SELECT examples​

Gets detailed information about a stream, including the number of partitions.

SELECT
id,
name,
compartmentId,
definedTags,
freeformTags,
lifecycleState,
lifecycleStateDetails,
messagesEndpoint,
partitions,
retentionInHours,
streamPoolId,
timeCreated
FROM oci.streaming.streams
WHERE streamId = '{{ streamId }}' -- required
AND region = '{{ region }}' -- required
AND opc-request-id = '{{ opc-request-id }}'
;

INSERT examples​

Starts the provisioning of a new stream.<br />The stream will be created in the given compartment id or stream pool id, depending on which parameter is specified.<br />Compartment id and stream pool id cannot be specified at the same time.<br />To track the progress of the provisioning, you can periodically call [GetStream](#/en/streaming/20180418/Stream/GetStream).<br />In the response, the lifecycleState parameter of the [Stream](#/en/streaming/20180418/Stream/) object tells you its current state.<br />

INSERT INTO oci.streaming.streams (
compartmentId,
definedTags,
freeformTags,
name,
partitions,
retentionInHours,
streamPoolId,
region,
opc-request-id
)
SELECT 
'{{ compartmentId }}',
'{{ definedTags }}',
'{{ freeformTags }}',
'{{ name }}' /* required */,
{{ partitions }} /* required */,
{{ retentionInHours }},
'{{ streamPoolId }}',
'{{ region }}',
'{{ opc-request-id }}'
RETURNING
id,
name,
compartmentId,
definedTags,
freeformTags,
lifecycleState,
lifecycleStateDetails,
messagesEndpoint,
partitions,
retentionInHours,
streamPoolId,
timeCreated
;

UPDATE examples​

Updates the stream. Only specified values will be updated.<br />

UPDATE oci.streaming.streams
SET 
definedTags = '{{ definedTags }}',
freeformTags = '{{ freeformTags }}',
streamPoolId = '{{ streamPoolId }}'
WHERE 
streamId = '{{ streamId }}' --required
AND region = '{{ region }}' --required
AND opc-request-id = '{{ opc-request-id}}'
AND if-match = '{{ if-match}}'
RETURNING
id,
name,
compartmentId,
definedTags,
freeformTags,
lifecycleState,
lifecycleStateDetails,
messagesEndpoint,
partitions,
retentionInHours,
streamPoolId,
timeCreated;

DELETE examples​

Deletes a stream and its content. Stream contents are deleted immediately. The service retains records of the stream itself for 90 days after deletion.<br />The lifecycleState parameter of the Stream object changes to DELETING and the stream becomes inaccessible for read or write operations.<br />To verify that a stream has been deleted, make a [GetStream](#/en/streaming/20180418/Stream/GetStream) request. If the call returns the stream's<br />lifecycle state as DELETED, then the stream has been deleted. If the call returns a "404 Not Found" error, that means all records of the<br />stream have been deleted.<br />

DELETE FROM oci.streaming.streams
WHERE streamId = '{{ streamId }}' --required
AND region = '{{ region }}' --required
AND opc-request-id = '{{ opc-request-id }}'
AND if-match = '{{ if-match }}'
;

Lifecycle Methods​

Moves a resource into a different compartment.<br />When provided, If-Match is checked against ETag values of the resource.<br />The stream will also be moved into the default stream pool in the destination compartment.<br />

EXEC oci.streaming.streams.change_compartment 
@streamId='{{ streamId }}' --required, 
@region='{{ region }}' --required, 
@if-match='{{ if-match }}', 
@opc-request-id='{{ opc-request-id }}' 
@@json=
'{
"compartmentId": "{{ compartmentId }}"
}'
;