TRY ME

Try Valo for free

We want to show you something amazing.

We'll send you a link to download a fully functional Valo copy to play with.



Great! Check your email and enjoy Valo



Apologies, we seem to be having a problem processing your input, please try again

Execution API

See the execution session documentation for an overview of sessions.

Create a new session

In order to access the execution service, the client MUST obtain a session first:

POST /execution/:tenant/sessions

This request will create a new empty session with a randomly generated UUID. The returned uri should be used to interact with the session.

Warning

The session is durable, meaning it will be kept alive until it is explicitly deleted by the client.

Example request:

POST /execution/demo/sessions HTTP/1.1

Example response:

HTTP/1.1 200 OK

{
    "session": "/execution/demo/sessions/4dc03528-59c8-4cb4-8618-71c26681484e"
}

If the tenant doesn’t exist a 404 will be returned.

Get a session

GET /execution/:tenant/sessions/:id

Retrieves the specified session.

Example request:

GET /execution/demo/sessions/4dc03528-59c8-4cb4-8618-71c26681484e HTTP/1.1

Example response:

HTTP/1.1 200 OK

{
  "domain": null,
  "queries": [
    {
      "id": "q1",
      "query_type": "valo-query-lang",
      "body": "from /streams/eq/infrastructure/does_not_exist where user > 50",
      "variables": []
    }
  ],
  "variables": []
}

If the session doesn’t exist a 404 will be returned.

Delete a session

DELETE /execution/:tenant/sessions/:id

Removes the specified session.

Example request:

DELETE /execution/demo/sessions/4dc03528-59c8-4cb4-8618-71c26681484e HTTP/1.1

Example response:

HTTP/1.1 200 OK

{}

If the session doesn’t exist a 404 will be returned.

Put an execution environment

PUT /execution/:tenant/sessions/:id

Creates or updates an environment context. The id is specified by the user and it MUST the session UUID generated by Valo. The queries MAY include the field query_type, but only valo-query-lang is supported at the moment. The query id MUST be a unique identifier. The domain field specifies a domain which should filter the query input. This attribute MAY be omitted (ie. unfiltered results for the query)

Warning

If an existing document is updated, the entire state in Valo for the execution context will be reset.

Example request:

PUT /execution/demo/sessions/4dc03528-59c8-4cb4-8618-71c26681484e HTTP/1.1
Content-Type: application/json

{
  "domain" : "/domain/demo/support/my_servers",
  "variables" : [
    { "id": "tradeId", "value": "ABC123", "type": "string" }
  ],
  "functions": [
    {
       "id": "e854287e-5c6c-408d-a0f4-257ef5f8fc89",
       "language": "js",
       "body": "function sum(a, b) return a + b"
    }
  ],
  "queries": [
    {
        "id": "q1",
        "body": "from logs where contains(msg, @tradeId) into stream msgs",
        "variables": [
          { "id": "tradeId", "value": "ABC123", "type": "string" }
        ]
    },
    {
        "id": "q2",
        "query_type": "valo-query-lang",
        "body": "from msgs window of 1 hour select count()"
    }
  ]
}

Response:

Returns the same as a call to GET /execution/:tenant/sessions/:id/queries

Put a domain

PUT /execution/:tenant/sessions/:id/domain

Sets the domain. Any running queries depending on this field will be restarted. The domain attribute is not mandatory.

Example request:

PUT /execution/demo/sessions/4dc03528-59c8-4cb4-8618-71c26681484e/domain HTTP/1.1
Content-Type: application/json

{
    "domain": "/domains/demo/support/my_servers"
}

Response:

Returns the same as a call to GET /execution/:tenant/sessions/:id/queries

Get a domain

GET /execution/:tenant/sessions/:id/domain

Gets the domain.

Example request:

GET /execution/demo/sessions/4dc03528-59c8-4cb4-8618-71c26681484e/domain HTTP/1.1

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "domain": "/domains/demo/support/my_servers"
}

If no domain has been set, a 404 is returned

Delete a domain

DELETE /execution/:tenant/sessions/:id/domain

Deletes the domain. Any running queries depending on this field will be restarted.

Example request:

DELETE /execution/demo/sessions/4dc03528-59c8-4cb4-8618-71c26681484e/domain HTTP/1.1

Response:

Returns the same as a call to GET /execution/:tenant/sessions/:id/queries

Put a variable

PUT /execution/:tenant/sessions/:id/variables

Adds a new variable or updates an existing one. Any running queries depending on this field will be restarted.

Example request:

PUT /execution/demo/sessions/4dc03528-59c8-4cb4-8618-71c26681484e/variables HTTP/1.1
Content-Type: application/json

{ "id": "tradeId", "value": "ABC123", "type": "string" }

Response:

Returns the same as a call to GET /execution/:tenant/sessions/:id/queries.

Get a variable

GET /execution/:tenant/sessions/:id/variables/:varId

Gets a variable.

Example request:

GET /execution/demo/sessions/4dc03528-59c8-4cb4-8618-71c26681484e/variables/tradeId HTTP/1.1

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{ "value": "ABC123", "type": "string" }

Delete a variable

DELETE /execution/:tenant/sessions/:id/variables/:varId

Deletes an existing variable. Any running queries depending on this field will be restarted.

Example request:

DELETE /execution/demo/sessions/4dc03528-59c8-4cb4-8618-71c26681484e/variables/tradeId HTTP/1.1

Response:

Returns the same as a call to GET /execution/:tenant/sessions/:id/queries

Put a query

PUT /execution/:tenant/sessions/:id/queries

Adds a new query or updates an existing one. If the query is currently running it will be stopped and restarted. Any downstream query dependencies will also be restarted.

The language used for the query can specified as query_type. Without this, the default language is used.

Currently supported languages:

  • valo-query-lang

Example request:

PUT /execution/demo/sessions/4dc03528-59c8-4cb4-8618-71c26681484e/queries HTTP/1.1
Content-Type: application/json

{
    "id": "q3",
    "body": "from logs where contains(msg, @tradeId) into stream msgs",
    "query_type": "valo-query-lang",
    "variables": [
       { "id": "tradeId", "value": "ABC123", "type": "string" }
    ]
}

Response:

Returns the same as a call to GET /execution/:tenant/sessions/:id/queries. If the new query has errors, they must be solved by the end user so that it can be added to the runtime.

Delete a query

DELETE /execution/:tenant/sessions/:id/queries/:queryId

Deletes an existing query. If the query is currently running it will be stopped and deleted. Any downstream query dependencies will be stopped.

Example request:

DELETE /execution/demo/sessions/4dc03528-59c8-4cb4-8618-71c26681484e/queries/4396307e-9eec-4496-8edf-670df89aac77 HTTP/1.1

Response:

Returns the same as a call to GET /execution/:tenant/sessions/:id/queries

Get a query

GET /execution/:tenant/sessions/:id/queries/:queryId

Gets the current query state. This does not execute the query but it evaluates the input dependencies and output schema.

Example request:

GET /execution/demo/sessions/4dc03528-59c8-4cb4-8618-71c26681484e/queries/4396307e-9eec-4496-8edf-670df89aac77 HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "dependencies" : [
    { "type": "query", "id": "q1" },
    { "type": "variable", "id": "tradeId" }
  ],
  "query": {
    "state": "initialised",
    "outputs": [
      {
        "type": "OUTPUT_CHANNEL",
        "id": "cee12b3b-4335-40ef-b3c8-e0c65bcc6bb4",
        "outputUri": "/output/demo/6daccb6739b02bacda2d4c37428263d3/5264726f-e17b-4bb4-bc44-f45be8fdb44e",
        "outputType": "BOUNDED",
        "isHistorical": true,
        "schema": {
          "version": "",
          "config": {
            "key": []
          },
          "topDef": {
            "type": "record",
            "properties": {
            "name": { "type": "string"},
            "contributor": {
              "type": "contributor",
              "uri": { "tenant": "demo", "collection": "probes" }
            }
          }
         }
        }
      }
    ]
  }
}

The output type can be any of the following types.

Errors

If any errors are found an error collection is returned.

HTTP/1.1 400 OK
Content-Type: application/json

{
  "errors" : [
    { "type": "MISSING_VARIABLE", "name": "tradeDate", "expectedType": "date" }
  ]
}

The endpoint might respond with any of the following errors.

Get the queries

GET /execution/:tenant/sessions/:id/queries

Gets the current query state for each of the queries defined in the execution context. This is the same as calling GET /execution/:tenant/:id/queries/:queryId for each query defined in the execution context.

Example request:

GET /execution/demo/sessions/4dc03528-59c8-4cb4-8618-71c26681484e/queries HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "q1",
    "dependencies": [],
    "query": {
      "state": "initialised",
      "outputs": [
        {
          "type": "OUTPUT_CHANNEL",
          "id": "cee12b3b-4335-40ef-b3c8-e0c65bcc6bb4",
          "outputUri": "/output/demo/6daccb6739b02bacda2d4c37428263d3/5264726f-e17b-4bb4-bc44-f45be8fdb44e",
          "outputType": "BOUNDED",
          "isHistorical": true,
          "schema": {
            "version": "",
            "config": {
              "key": []
            },
            "topDef": {
              "type": "record",
              "properties": {
                "name": { "type": "string" },
                "contributor": {
                  "type": "contributor",
                  "uri": { "tenant": "demo", "collection": "probes"}
                }
              }
            }
          }
        }
      ]
    }
  },
  {
    "id": "q2",
    "errors": [
      {
        "type": "INVALID_FIELD_REFERENCE",
        "field": "contributor2"
      }
    ]
  }
]

Start a query

PUT /execution/:tenant/sessions/:id/queries/:queryId/_start

Starts the query. Also starts any upstream queries this query depends on.

Example request:

PUT /execution/demo/sessions/4dc03528-59c8-4cb4-8618-71c26681484e/queries/q1/_start HTTP/1.1

Response:

Returns the same as a call to GET /execution/:tenant/sessions/:id/queries

Stop a query

PUT /execution/:tenant/sessions/:id/queries/:queryId/_stop

Stops the query. Also stops any downstream queries which depends on this.

Example request:

PUT /execution/demo/sessions/4dc03528-59c8-4cb4-8618-71c26681484e/queries/q1/_stop HTTP/1.1

Response:

Returns the same as a call to GET /execution/:collection/:tenant/:id/queries

Daemonise a query

PUT /execution/:tenant/sessions/:id/queries/:queryId/_daemonise

Daemonises a query. This end-point is a convenient way of daemonizing a query within a session. The same can be achieved by using the daemon service API

Refer to the daemon settings for description of the possible settings.

Example request:

PUT /execution/demo/sessions/4dc03528-59c8-4cb4-8618-71c26681484e/queries/q1/_daemonise HTTP/1.1
Content-Type: application/json

{
   "contributor": "/contributors/demo/probes/instances/9a2df62c-f97d-4971-932d-0099bc4efa49",
   "target": {
      "type": "QUERY"
   }
}

Example response:

The result is an URI to the daemonised query.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "daemonUri": "/daemon/demo/system/7701eab8-ba30-45e1-89e4-50dc2df88e8b"
}
statuscode 200:the daemonisation has been successful