CreateStream

On This Page

Description

Creates and configures a new stream. The configuration includes the stream's shard count and retention period. The new stream is available immediately upon its creation.

Request

Request Header

Syntax
    POST /<container>/<resource> HTTP/1.1
Host: <web-APIs URL>
Content-Type: application/json
X-v3io-function: CreateStream
<Authorization OR X-v3io-session-key>: <value>

    url = "http://<web-APIs URL>/<container>/<resource>"
headers = {
            "Content-Type": "application/json",
            "X-v3io-function": "CreateStream",
            "<Authorization OR X-v3io-session-key>": "<value>"
          }
    URL Resource Parameters

    The path to the new stream. You can optionally set the stream name in the request's StreamName JSON parameter instead of in the URL.

    Request Data

    Syntax
      {
    "StreamName":           "string",
    "ShardCount":           number,
    "RetentionPeriodHours": number
}

      payload = {
            "StreamName":           "string",
            "ShardCount":           number,
            "RetentionPeriodHours": number
          }
      Parameters
      StreamName

      A unique name for the new stream (collection) that will be created.

      • Type: String
      • Requirement: Required if not set in the request URL
      ShardCount

      The steam's shard count, i.e., the number of stream shards to create.

      • Type: Number
      • Requirement: Required
      • Valid Values: A positive integer (>= 1). For example, 100.
      • Default Value: 1

      RetentionPeriodHours

      The stream's retention period, in hours. After this period elapses, when new records are added to the stream, the earliest ingested records are deleted.

      • Type: Number
      • Requirement: Required
      • Valid Values: A positive integer (>= 1). For example, 2 (2 hours).
      • Default Value: 24 (1 day)

      Response

      Response Data

      None

      Errors

      In the event of an error, the response includes a JSON object with an ErrorCode element that contains a unique numeric error code, and an ErrorMessage element that contains one of the following API error messages:
      Error Message Description
      InvalidArgumentException A provided request parameter is not valid for this request.
      Permission denied The sender of the request does not have the required permissions to perform the operation.
      ResourceInUseException A collection already exists in the specified stream path.

      Examples

      Create a stream named mycontainer with 1000 shards and a retention period of one hour:

      Request
        POST /mycontainer/MyStream/ HTTP/1.1
Host: https://default-tenant.app.mycluster.iguazio.com:8443
Content-Type: application/json
X-v3io-function: CreateStream
X-v3io-session-key: e8bd4ca2-537b-4175-bf01-8c74963e90bf

        {
    "ShardCount":           1000,
    "RetentionPeriodHours": 1
}

        import requests

url = "https://default-tenant.app.mycluster.iguazio.com:8443/mycontainer/MyStream/"
headers = {
            "Content-Type": "application/json",
            "X-v3io-function": "CreateStream",
            "X-v3io-session-key": "e8bd4ca2-537b-4175-bf01-8c74963e90bf"
          }
payload = {"ShardCount": 1000, "RetentionPeriodHours": 1}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
        Response
        HTTP/1.1 200 OK
Content-Type: application/json