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
}