clearml-server/apiserver/schema/services/queues.conf

_description: "Provides a management API for queues of tasks waiting to be executed by workers deployed anywhere (see Workers Service)."
_definitions {
    include "_common.conf"
    queue_metrics {
        type: object
        properties: {
            queue: {
                type: string
                description: "ID of the queue"
            }
            dates {
                type: array
                description: "List of timestamps (in seconds from epoch) in the acceding order. The timestamps are separated by the requested interval. Timestamps where no queue status change was recorded are omitted."
                items { type: integer }
            }
            avg_waiting_times {
                type: array
                description: "List of average waiting times for tasks in the queue. The points correspond to the timestamps in the dates list. If more than one value exists for the given interval then the maximum value is taken."
                items { type: number }
            }
            queue_lengths {
                type: array
                description: "List of tasks counts in the queue. The points correspond to the timestamps in the dates list. If more than one value exists for the given interval then the count that corresponds to the maximum average value is taken."
                items { type: integer }
            }
        }
    }
    entry {
        type: object
        properties: {
            task {
                description: "Queued task ID"
                type: string
            }
            added {
                description: "Time this entry was added to the queue"
                type: string
                format: "date-time"
            }
        }
    }
    queue {
        type: object
        properties: {
            id {
                description: "Queue id"
                type: string
            }
            name {
                description: "Queue name"
                type: string
            }
            user {
                description: "Associated user id"
                type: string
            }
            company {
                description: "Company id"
                type: string
            }
            created {
                description: "Queue creation time"
                type: string
                format: "date-time"
            }
            tags {
                description: "User-defined tags"
                type: array
                items { type: string }
            }
            system_tags {
                description: "System tags. This field is reserved for system use, please don't use it."
                type: array
                items { type: string }
            }
            entries {
                description: "List of ordered queue entries"
                type: array
                items { "$ref": "#/definitions/entry" }
            }
            metadata {
                description: "Queue metadata"
                "$ref": "#/definitions/metadata"
            }
        }
    }
}

get_by_id {
    "2.4" {
        description: "Gets queue information"
        request {
            type: object
            required: [ queue ]
            properties {
                queue {
                    description: "Queue ID"
                    type: string
                }
            }
        }
        response {
            type: object
            properties {
                queue {
                    description: "Queue info"
                    "$ref": "#/definitions/queue"
                }
            }
        }
    }
}
// typescript generation hack
get_all_ex {
    internal: true
    "2.4": ${get_all."2.4"}
}
get_all {
    "2.4" {
        description: "Get all queues"
        request {
            type: object
            properties {
                name {
                    description: "Get only queues whose name matches this pattern (python regular expression syntax)"
                    type: string
                }
                id {
                    description: "List of Queue IDs used to filter results"
                    type: array
                    items { type: string }
                }
                tags {
                    description: "User-defined tags list used to filter results. Prepend '-' to tag name to indicate exclusion"
                    type: array
                    items { type: string }
                }
                system_tags {
                    description: "System tags list used to filter results. Prepend '-' to system tag name to indicate exclusion"
                    type: array
                    items { type: string }
                }
                page {
                    description: "Page number, returns a specific page out of the result list of results."
                    type: integer
                    minimum: 0
                }
                page_size {
                    description: "Page size, specifies the number of results returned in each page (last page may contain fewer results)"
                    type: integer
                    minimum: 1
                }
                order_by {
                    description: "List of field names to order by. When search_text is used, '@text_score' can be used as a field representing the text score of returned documents. Use '-' prefix to specify descending order. Optional, recommended when using page"
                    type: array
                    items { type: string }
                }
                search_text {
                    description: "Free text search query"
                    type: string
                }
                only_fields {
                    description: "List of document field names (nesting is supported using '.', e.g. execution.model_labels). If provided, this list defines the query's projection (only these fields will be returned for each result entry)"
                    type: array
                    items { type: string }
                }
            }
        }
        response {
            type: object
            properties {
                queues {
                    description: "Queues list"
                    type: array
                    items { "$ref": "#/definitions/queue"}
                }
            }
        }
    }
}
get_default {
    "2.4" {
        description: ""
        request {
            type: object
            properties {}
            additionalProperties: false
        }
        response {
            type: object
            properties {
                id {
                    description: "Queue id"
                    type: string
                }
                name {
                    description: "Queue name"
                    type: string
                }
            }
        }
    }
}
create {
    "2.4" {
        description: "Create a new queue"
        request {
            type: object
            required: [ name ]
            properties {
                name {
                    description: "Queue name Unique within the company."
                    type: string
                }
                tags {
                    description: "User-defined tags list"
                    type: array
                    items { type: string }
                }
                system_tags {
                    description: "System tags list. This field is reserved for system use, please don't use it."
                    type: array
                    items { type: string }
                }
            }
        }
        response {
            type: object
            properties {
                id {
                    description: "New queue ID"
                    type: string
                }
            }
        }
    }
}
update {
    "2.4" {
        description: "Update queue information"
        request {
            type: object
            required: [ queue ]
            properties {
                queue {
                    description: "Queue id"
                    type: string
                }
                name {
                    description: "Queue name Unique within the company."
                    type: string
                }
                tags {
                    description: "User-defined tags list"
                    type: array
                    items { type: string }
                }
                system_tags {
                    description: "System tags list. This field is reserved for system use, please don't use it."
                    type: array
                    items { type: string }
                }
            }
        }
        response {
            type: object
            properties {
                updated {
                    description: "Number of queues updated (0 or 1)"
                    type: integer
                    enum: [ 0, 1 ]
                }
                fields {
                    description: "Updated fields names and values"
                    type: object
                    additionalProperties: true
                }

            }
        }
    }
}
delete {
    "2.4" {
        description: "Deletes a queue. If the queue is not empty and force is not set to true, queue will not be deleted."
        request {
            type: object
            required: [ queue ]
            properties {
                queue {
                    description: "Queue id"
                    type: string
                }
                force {
                    description: "Force delete of non-empty queue. Defaults to false"
                    type: boolean
                    default: false
                }
            }
        }
        response {
            type: object
            properties {
                deleted {
                    description: "Number of queues deleted (0 or 1)"
                    type: integer
                    enum: [ 0, 1 ]
                }
            }
        }
    }
}
add_task {
    "2.4" {
        description: "Adds a task entry to the queue."
        request {
            type: object
            required: [
                queue
                task
            ]
            properties {
                queue {
                    description: "Queue id"
                    type: string
                }
                task {
                    description: "Task id"
                    type: string
                }
            }
        }
        response {
            type: object
            properties {
                added {
                    description: "Number of tasks added (0 or 1)"
                    type: integer
                    enum: [ 0, 1 ]
                }
            }
        }
    }
}
get_next_task {
    "2.4" {
        description: "Gets the next task from the top of the queue (FIFO). The task entry is removed from the queue."
        request {
            type: object
            required: [ queue ]
            properties {
                queue {
                    description: "Queue id"
                    type: string
                }
            }
        }
        response {
            type: object
            properties {
                entry {
                    description: "Entry information"
                    "$ref": "#/definitions/entry"
                }
            }
        }
    }
}
remove_task {
    "2.4" {
        description: "Removes a task entry from the queue."
        request {
            type: object
            required: [
                queue
                task
            ]
            properties {
                queue {
                    description: "Queue id"
                    type: string
                }
                task {
                    description: "Task id"
                    type: string
                }
            }
        }
        response {
            type: object
            properties {
                removed {
                    description: "Number of tasks removed (0 or 1)"
                    type: integer
                    enum: [ 0, 1 ]
                }
            }
        }
    }
}

move_task_forward: {
    "2.4" {
        description: "Moves a task entry one step forward towards the top of the queue."
        request {
            type: object
            required: [
                queue
                task
            ]
            properties {
                queue {
                    description: "Queue id"
                    type: string
                }
                task {
                    description: "Task id"
                    type: string
                }
                count {
                    description: "Number of positions in the queue to move the task forward relative to the current position. Optional, the default value is 1."
                    type: integer
                }
            }
        }
        response {
            type: object
            properties {
                position {
                    description: "The new position of the task entry in the queue (index, -1 represents bottom of queue)"
                    type: integer
                }
            }
        }
    }
}
move_task_backward: {
    "2.4" {
        description: ""
        request {
            type: object
            required: [
                queue
                task
            ]
            properties {
                queue {
                    description: "Queue id"
                    type: string
                }
                task {
                    description: "Task id"
                    type: string
                }
                count {
                    description: "Number of positions in the queue to move the task forward relative to the current position. Optional, the default value is 1."
                    type: integer
                }
            }
        }
        response {
            type: object
            properties {
                position {
                    description: "The new position of the task entry in the queue (index, -1 represents bottom of queue)"
                    type: integer
                }
            }
        }
    }
}
move_task_to_front: {
    "2.4" {
        description: ""
        request {
            type: object
            required: [
                queue
                task
            ]
            properties {
                queue {
                    description: "Queue id"
                    type: string
                }
                task {
                    description: "Task id"
                    type: string
                }
            }
        }
        response {
            type: object
            properties {
                position {
                    description: "The new position of the task entry in the queue (index, -1 represents bottom of queue)"
                    type: integer
                }
            }
        }
    }
}
move_task_to_back: {
    "2.4" {
        description: ""
        request {
            type: object
            required: [
                queue
                task
            ]
            properties {
                queue {
                    description: "Queue id"
                    type: string
                }
                task {
                    description: "Task id"
                    type: string
                }
            }
        }
        response {
            type: object
            properties {
                position {
                    description: "The new position of the task entry in the queue (index, -1 represents bottom of queue)"
                    type: integer
                }
            }
        }
    }
}
get_queue_metrics : {
    "2.4" {
        description: "Returns metrics of the company queues. The metrics are avaraged in the specified interval."
        request {
            type: object
            required: [from_date, to_date, interval]
            properties: {
                from_date {
                    description: "Starting time (in seconds from epoch) for collecting metrics"
                    type: number
                }
                to_date {
                    description: "Ending time (in seconds from epoch) for collecting metrics"
                    type: number
                }
                interval {
                    description: "Time interval in seconds for a single metrics point. The minimal value is 1"
                    type: integer
                }
                queue_ids {
                    description: "List of queue ids to collect metrics for. If not provided or empty then all then average metrics across all the company queues will be returned."
                    type: array
                    items { type: string }
                }
            }
        }
        response {
            type: object
            properties: {
                queues {
                    type: array
                    description: "List of the requested queues with their metrics. If no queue ids were requested then 'all' queue is returned with the metrics averaged accross all the company queues."
                    items { "$ref": "#/definitions/queue_metrics" }
                }
            }
        }
    }
}
add_or_update_metadata {
    "2.13" {
        description: "Add or update queue metadata"
        request {
            type: object
            required: [queue, metadata]
            properties {
                queue {
                    description: "ID of the queue"
                    type: string
                }
                metadata {
                    description: "Metadata items to add or update"
                    "$ref": "#/definitions/metadata"
                }
            }
        }
        response {
            type: object
            properties {
                updated {
                    description: "Number of queues updated (0 or 1)"
                    type: integer
                    enum: [0, 1]
                }
            }
        }
    }
}
delete_metadata {
    "2.13" {
        description: "Delete metadata from queue"
        request {
            type: object
            required: [ queue, keys ]
            properties {
                queue {
                    description: "ID of the queue"
                    type: string
                }
                keys {
                    description: "The list of metadata keys to delete"
                    type: array
                    items {type: string}
                }
            }
        }
        response {
            type: object
            properties {
                updated {
                    description: "Number of queues updated (0 or 1)"
                    type: integer
                    enum: [0, 1]
                }
            }
        }
    }
}