Before a user can add records, all referenced schema elements (Spaces, Containers, Properties) must be defined/created in Data Modeling
To add records, the user must have capabilities to access (read to) the referenced containers as well as capabilities to access (write to) the referenced record space.
Batches of records are ingested into a stream.
Under normal ingestion operation, and where the data stream does not contain any duplicated records,
the record will be created, and the properties defined in each of the containers in the sources array will be populated.
For immutable streams a duplicate record is defined as one which is being written to the same space,
which uses the same container definitions in the sources array,
and all the properties (names and values) are the same.
For immutable streams under most circumstances, when duplicate records are encountered during ingestion, the duplicate is discarded. However there are rare occasions when certain internal database operations occur, a duplicate may be stored.
For mutable streams duplicated record identifiers (space + externalId) are not allowed
and a request which tries to create a record with existing identifier will be rejected.
Note: The maximum total request size is 10MB.
Records to ingest into a stream.
required | Array of objects (recordItems) [ 1 .. 1000 ] items List of records to write. |
An empty response is returned if all records from the request are successfully accepted to be created or updated.
The response for a failed request.
Some mutable records with the specified space and externalId already exist in the stream.
But some records might have been created successfully.
Which records were successfully created and which were rejected with a conflict can be understood from the response content.
Note: the error may appear due to some HTTP request retries (in intermediate components like SDK, Load balancers, Application Gateway, etc),
so better to check which records are in the stream when you receive this error.
.../records/filter or .../records/sync endpoints with a filter by space and externalId can be used to check the stored state of the conflicting records.
Some mutable record identifiers (space and externalId) are duplicated in the request.
If at least one record was not ingested due to an internal error, and all other errors in the failed list were non-retryable,
this error code will be returned.
Note: Record operations are not transactional. This means that during batch ingestion, some records may be created successfully even if the creation of others fails. The response body indicates which records were successfully created and which were not.
An internal server error usually indicates an issue that requires investigation. A simple retry might not help, but a few retries could be a reasonable approach.
Note: If you choose to retry on a 500 error, it is recommended to retry only the failed records rather than the entire request. For mutable streams this helps avoid receiving 409 status codes records that were already successfully created in a previous attempt. For immutable streams, this helps prevent accidental duplicate records from appearing in the stream (in rare cases when the deduplication mechanism fails).
If at least one record was not ingested due to the service being temporarily unavailable, this error code will be returned.
Note: Record operations are not transactional. This means that during batch ingestion, some records may be created successfully even if the creation of others fails. The response body indicates which records were successfully created and which were not.
A "service temporarily unavailable" error usually indicates a temporary issue, and several retries may help complete the record creation.
Note: It is recommended to retry ingestion of only the failed records rather than the entire request. For mutable streams, this helps avoid receiving 409 status codes for records that were already successfully created in a previous attempt. For immutable streams, this helps prevent accidental duplicate records from appearing in the stream (in rare cases when the deduplication mechanism fails).
{- "items": [
- {
- "space": "mySpace",
- "externalId": "some_id",
- "sources": [
- {
- "source": {
- "type": "container,",
- "space": "mySpace,",
- "externalId": "myContainer"
}, - "properties": {
- "someStringProperty": "someStringValue",
- "someDirectRelation": {
- "space": "mySpace",
- "externalId": "someNode"
}, - "someIntArrayProperty": [
- 1,
- 2,
- 3,
- 4
]
}
}
]
}
]
}{ }