Skip to main content

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 ValueStatusDescription
0SuccessThe command was successful
1EmptyIf a class or property key was not present but used for searching.
2ExistsA conditional add found a unique instance of an existent object.
3NotUniqueA search query specified "unique" = true but got multiple results.
4Response size is too largeA query is attempting to retrieve binary data larger than allowed (default is 256MB).
-1ErrorThere 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
}