Purpose

The read operation in JQL is used to retrieve resources from Antly’s backend system. This operation allows you to query the database and retrieve data based on specified criteria. The read operation can be used to retrieve a single resource or a list of resources, with options for filtering, sorting, and pagination.

Syntax

The JSON structure for a read operation in JQL typically includes the following components:

• __meta__: Metadata about the query, including authentication details, the intent (retrieve), the target namespace, and the schema.
• Filter Criteria: Optional criteria to filter the results.
• Ordering: Optional array to specify the order of the results.
• Pagination: Optional parameters to limit the number of results and manage pagination.

General Read Operation Structure:

{
    "__meta__": {
        "authenticationClass": "<authentication_method>",
        "intent": "retrieve",
        "namespace": "<module_name>",
        "schema": "<schema_type>",
        "filter": { "<filter_criteria>": "<value>" }, // Optional: Filters to apply
        "exclude": { "<field_to_exclude>": "<value>" }, // Optional: Fields to exclude
        "search": {
            "value": "<search_term>" // Optional: Search term
        },
        "ordering": [
            "<field_name>", // Optional: Field to order by
            "-<field_name>" // Optional: Field to order by in descending order
        ],
        "cache": {
            "enabled": <true_or_false> // Optional: Caching control
        },
        "limit": <number_of_results>, // Optional: Number of results to return
        "offset": <number_of_results_to_skip>, // Optional: Number of results to skip for pagination
        "draw": <draw_number> // Optional: Tracking number for the draw
    },
    "<field_name_1>": null,
    "<field_name_2>": null,
    // Additional fields as needed
}

Filters

Filters are used in read operations to narrow down the results based on specific criteria. You can specify multiple filters in the filter object, and only records matching these criteria will be returned.

Example Filter Structure:

"filter": {
    "age": "18",
    "status": "active"
}

In this example, the query would return records where the age is 18 and the status is active.

Pagination

Pagination is managed through the limit and offset parameters in the __meta__ object. These parameters help control the number of records returned in a single query and the point at which the query starts.

• limit: Specifies the maximum number of results to return.
• offset: Specifies the number of results to skip before starting to return results.

Ordering is also a key component of pagination. The ordering array allows you to define the order in which results are returned. To sort by a nested field, you can use the dot notation (e.g., "field1.field2"). To sort in descending order, prefix the field name with a minus sign ("-field_name").

Example Pagination Structure:

"limit": 10,
"offset": 10,
"ordering": [
    "created_at",
    "-fullname"
]

In this example, the query returns 10 results, starting from the 11th record (offset of 10), ordered first by the created_at field in ascending order, and then by the fullname field in descending order.

Example: Sample Query

Let's assume we are retrieving a list of young persons from the objects.YoungPerson namespace. The query would look like this:

{
    "__meta__": {
        "authenticationClass": "session",
        "intent": "retrieve",
        "namespace": "objects.YoungPerson",
        "schema": "model",
        "filter": {
            "status": "active"
        },
        "exclude": {
            "sensitive_info": true
        },
        "search": {
            "value": "John"
        },
        "ordering": [
            "created_at",
            "-fullname"
        ],
        "cache": {
            "enabled": false
        },
        "limit": 10,
        "offset": 10,
        "draw": 1
    },
    "first_name": null,
    "last_name": null,
    "age": null,
    "status": null
}

In this example:

• authenticationClass: Indicates that session-based authentication is used.
• intent: Specifies the operation as retrieve.
• namespace: Targets the objects.YoungPerson module.
• schema: Indicates that the operation is on the model schema.
• filter: Filters results to include only active records.
• exclude: Excludes sensitive information from the results.
• search: Searches for records containing "John" in relevant fields.
• ordering: Orders results first by created_at in ascending order and then by fullname in descending order.
• limit: Limits the results to 10 records.
• offset: Starts returning results from the 11th record.
• Data Fields: Specifies the fields to be included in the response.

Example: Sample Response

Upon successful execution of the read operation, the response might look like this:

{
    "status": "OK",
    "data": [
        {
            "first_name": "John",
            "last_name": "Doe",
            "age": "18",
            "status": "active"
        },
        {
            "first_name": "Jane",
            "last_name": "Smith",
            "age": "19",
            "status": "active"
        }
        // More records up to the limit of 10
    ],
    "errors": null,
    "il8n": "en-gb",
    "extras": {
        "filtered": 50,
        "display": 10,
        "queries": 1
    },
    "system_info": null,
    "intent": "retrieve",
    "message": null
}

In this response:

• status: Indicates that the operation was successful (OK).
• data: Contains an array of records that match the query criteria.
• errors: Will be null if no errors occurred.
• il8n: Specifies the locale used (en-gb).
• extras: Provides additional details about the operation, such as the number of filtered and displayed results.
• intent: Reflects the intent of the operation (retrieve).
• message: Could provide a human-readable message, if applicable.