Responses
In regular responses, the JSON response is an array of objects where each member gives information about how a particular command executed. Any time there is an error, the JSON response returned will not be an array but a JSON object with a member "status". So a check to see whether status is a member of response should reveal whether there was an error or not.
Responses for all the Find* commands indicate if "blobs" was set to true or false when requesting results. If "blobs" is true, there is an additional variable "blob_start" which gives the 0-based vector index for where the first blob corresponding to that command is placed in the return vector.
[
{
"CommandName": {
"status": <integer>, // Always present; status code
"returned": <integer>, // Always present; number of entities/connections/blobs returned
"blobs_start": <integer>, // Optional; present only if blobs=true
"entities": [ // Optional; present only if user requests entity property values
{
"_blob_index": <integer>, // Optional; present only if blobs=true
// ... requested entity properties
}
],
"connections": [ // Optional; present only if user requested connection property values
{
// ... requested connection properties
}
],
//... requested aggregated properties like count, average, etc
}
},
...
]
Field Descriptions
- status Indicates execution status (e.g., 0 for success).
- returned Indicates the number of entities, connections, or blobs returned. If the user requests only aggregated values (e.g., sum, average) or uses _ref without requesting any properties, "returned" will be 0.
- entities / connections Optional. Included only when the user explicitly requests property values.
- blobs_start Optional. Included only if blobs=true was set in the query. Indicates the 0-based index in the return vector where blob data for this command begins.
- _blob_index Optional. Included in each entity only if blobs=true. Indicates the blob's position relative to the full return vector.
Return Status
Each call returns a "status" with an integer value listed with its meaning in the table below. In case a command is unsuccessful, we return an error code and provide information on why it failed using the "info" field.
However, if there is a local id provided in such a call, we treat it as an exception which causes the rest of the transaction to abort. This is necessary to avoid relying on calls that were not successful. When a transaction aborts, it undoes all the metadata changes that were made until the point where the error occurred.
Return Value | Status | Description |
---|---|---|
0 | Success | The command was successful |
1 | Empty | If a class or property key was not present but used for searching. |
2 | Exists | A conditional add found a unique instance of an existent object. |
3 | NotUnique | A search query specified "unique" = true but got multiple results. |
4 | Response size is too large | A query is attempting to retrieve binary data larger than allowed (default is 256MB). |
-1 | Error | There was an error, the "info" field should provide a message. |
If every command within a transaction succeeded, ApertureDB will return one JSON object with the corresponding status code and results. If any of the commands fails, ApertureDB will return a single JSON object indicating the error status, information about what caused the failure, and the command that caused the failure.
Examples
# Successful AddEntity
"AddEntity" : {
"status": 0
}
# FindEntity with using a wrong "ref"
"FindEntity" : {
"status": -1,
"info": "Reference does not exist"
}
# If a Find*, let's say a FindEntity finds no matching object,
# the response is as shown here
"FindEntity" : {
"status": 0,
"returned": 0
}
# Responses for Find* commands with blobs
# Case 1: blobs=false and no matching objects
# The response will be similar to the one above.
# The array size of blobs will be 0.
# Case 2: blobs=true, matching objects found, but no properties requested
# The response includes "returned" and "blobs_start", but no "entities" array.
# For example, if 4 images matched:
"FindImage" : {
"status": 0,
"returned": 4,
"blobs_start": 0
}
# Case 3: blobs=true, matching objects found, and properties were requested
# The response includes an "entities" array.
# Each entity contains a "_blob_index" indicating its position in the blob vector.
# "blobs_start" shows the starting index for blobs associated with this command.
[
{
"FindImage": {
"blobs_start": 0,
"entities": [
{ "_blob_index": 0, "id": 0 },
{ "_blob_index": 1, "id": 2 },
{ "_blob_index": 2, "id": 4 }
],
"returned": 3,
"status": 0
}
},
{
"FindImage": {
"blobs_start": 3,
"entities": [
{ "_blob_index": 3, "id": 1 },
{ "_blob_index": 4, "id": 3 }
],
"returned": 2,
"status": 0
}
}
]
# Case 4: Aggregated results requested (e.g., count, sum, average)
# If "count" was set to true or aggregation functions like "sum" or "average" were requested,
# the response includes those fields along with "returned" and "blobs_start".
"FindImage": {
"status": 0,
"count": 4,
"returned": 4,
"blobs_start": 0
}