Search HTTP API

Prefix Searching

The /search endpoint returns matches for a given prefix and context, where a context can be jobs, allocations, evaluations, nodes, deployments, plugins, namespaces, or volumes. When using Nomad Enterprise, the allowed contexts include quotas. Additionally, a prefix can be searched for within every context.

Method	Path	Produces
`POST`	`/v1/search`	`application/json`

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`NO`	`node:read, namespace:read-jobs`

When ACLs are enabled, requests must have a token valid for node:read or namespace:read-jobs roles. If the token is only valid for node:read, then job related results will not be returned. If the token is only valid for namespace:read-jobs, then node results will not be returned.

Parameters

Prefix (string: <required>) - Specifies the identifier against which matches will be found. For example, if the given prefix were "a", potential matches might be "abcd", or "aabb".
Context (string: <required>) - Defines the scope in which a search for a prefix operates. Contexts can be: "jobs", "evals", "allocs", "nodes", "deployment", "plugins", "volumes" or "all", where "all" means every context will be searched.

Sample Payload (for all contexts)

{
  "Prefix": "abc",
  "Context": "all"
}

Sample Request

$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/search

Sample Response

{
  "Matches": {
    "allocs": null,
    "deployment": null,
    "evals": ["abc2fdc0-e1fd-2536-67d8-43af8ca798ac"],
    "jobs": ["abcde"],
    "nodes": null,
    "plugins": null,
    "volumes": null
  },
  "Truncations": {
    "allocs": "false",
    "deployment": "false",
    "evals": "false",
    "jobs": "false",
    "nodes": "false",
    "plugins": "false",
    "volumes": "false"
  }
}

Field Reference

Matches - A map of contexts to matching arrays of identifiers.
Truncations - Search results are capped at 20; if more matches were found for a particular context, it will be true.

Sample Payload (for a specific context)

{
  "Prefix": "abc",
  "Context": "evals"
}

Sample Request

$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/search

Sample Response

{
  "Matches": {
    "evals": ["abc2fdc0-e1fd-2536-67d8-43af8ca798ac"]
  },
  "Truncations": {
    "evals": "false"
  }
}

Fuzzy Searching

The /search/fuzzy endpoint returns partial substring matches for a given search term and context, where a context can be jobs, allocations, nodes, plugins, or namespaces. Additionally, fuzzy searching can be done across all contexts. For better control over the performance implications of fuzzy searching on Nomad servers, aspects of fuzzy searching can be tuned through the search block in Nomad agent config.

Fuzzy search results are ordered starting with closest matching terms. Items of a name that exactly matches the search term are listed first.

Method	Path	Produces
`POST`	`/v1/search/fuzzy`	`application/json`

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`NO`	`node:read, namespace:read-jobs, namespace:csi-list-plugin`

When ACLs are enabled, requests must have a token valid for node:read, plugin:read or namespace:read-jobs roles. If the token is only valid for a portion of these capabilities, then results will include results including only data readable with the given token.

Parameters

Text (string: <required>) - Specifies the identifier against which matches will be found. For example, if the given text were "py", potential fuzzy matches might be "python", "spying", or "happy".
Context (string: <required>) - Defines the scope in which a search for a prefix operates. Contexts can be: "jobs", "allocs", "nodes", "plugins", or "all", where "all" means every context will be searched. When "all" is selected, additional prefix matches will be included for the "deployments", "evals", and "volumes" types. When searching in the "jobs" context, results that fuzzy match "groups", "services", "tasks", "images", "commands", and "classes" are also included in the results.

Scope

Fuzzy match results are accompanied with a Scope field which is used to uniquely identify the matched object, in a way that the Nomad API can be queried again for additional information. The data provided by scope varies depending on the type of matched object, described below.

Sample Payload (for jobs)

{
  "Text": "py",
  "Context": "jobs"
}

Sample Request

$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/search/fuzzy

Sample Response

{
  "Index": 90,
  "KnownLeader": true,
  "LastContact": 0,
  "Matches": {
    "services": [
      {
        "ID": "python-logger",
        "Scope": [
          "default",
          "example-python",
          "my-spy-app",
          "my-python-task"
        ]
      },
      {
        "ID": "super-spy-service",
        "Scope": [
          "default",
          "example-python",
          "my-spy-app"
        ]
      }
    ],
    "tasks": [
      {
        "ID": "my-python-task",
        "Scope": [
          "default",
          "example-python",
          "my-spy-app"
        ]
      }
    ],
    "images": [
      {
        "ID": "python:3",
        "Scope": [
          "default",
          "example-python",
          "my-spy-app",
          "my-python-task"
        ]
      }
    ],
    "jobs": [
      {
        "ID": "example-python",
        "Scope": [
          "default"
        ]
      }
    ],
    "groups": [
      {
        "ID": "my-spy-app",
        "Scope": [
          "default",
          "example-python"
        ]
      }
    ]
  },
  "Truncations": {
    "jobs": false
  }
}

Scope (jobs)

Scope[0] : Namespace
Scope[1] : Job ID

Scope (groups)

Scope[0] : Namespace
Scope[1] : Job ID

Scope (tasks)

Scope[0] : Namespace
Scope[1] : Job ID
Scope[2] : Group

Scope (group services)

Scope[0] : Namespace
Scope[1] : Group

Scope (task services)

Scope[0] : Namespace
Scope[1] : Job ID
Scope[2] : Group
Scope[3] : Task

Scope (commands/images/classes)

Scope[0] : Namespace
Scope[1] : Job ID
Scope[2] : Group
Scope[3] : Task

Sample Payload (for nodes)

{
  "Text": "lab",
  "Context": "nodes"
}

Sample Request

$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/search/fuzzy

Sample Response

{
  "Index": 9,
  "KnownLeader": true,
  "LastContact": 0,
  "Matches": {
    "nodes": [
      {
        "ID": "nomad-lab1",
        "Scope": [
          "c48cd39f-dfe1-9cc0-9c62-617d199854be"
        ]
      }
    ]
  },
  "Truncations": {
    "nodes": false
  }
}

Scope (nodes)

Scope[0] : Node ID

Sample Payload (for allocs)

{
   "Text":"py",
   "Context":"allocs"
}

Sample Request

$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/search/fuzzy

Sample Response

{
  "Index": 136,
  "KnownLeader": true,
  "LastContact": 0,
  "Matches": {
    "allocs": [
      {
        "ID": "example-python.my-spy-app[0]",
        "Scope": [
          "default",
          "0fb703d1-ba4d-116f-13aa-27f31f046858"
        ]
      }
    ]
  },
  "Truncations": {
    "allocs": false
  }
}

Scope (allocs)

Scope[0] : Namespace
Scope[1] : Alloc ID

Sample Payload (for plugins)

{
  "Text": "aws",
  "Context": "plugins"
}

Sample Request

$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/search/fuzzy

Sample Response

{
  "Index": 0,
  "KnownLeader": true,
  "LastContact": 0,
  "Matches": {
    "plugins": [
      {
        "ID": "aws-efs0"
      }
    ]
  },
  "Truncations": {
    "plugins": false
  }
}

Sample Payload (for all)

{
  "Index": 260,
  "KnownLeader": true,
  "LastContact": 0,
  "Matches": {
    "services": [
      {
        "ID": "python-logger",
        "Scope": [
          "default",
          "example-python",
          "my-spy-app",
          "my-python-task"
        ]
      },
      {
        "ID": "super-spy-service",
        "Scope": [
          "default",
          "example-python",
          "my-spy-app"
        ]
      }
    ],
    "tasks": [
      {
        "ID": "my-python-task",
        "Scope": [
          "default",
          "example-python",
          "my-spy-app"
        ]
      }
    ],
    "jobs": [
      {
        "ID": "example-python",
        "Scope": [
          "default"
        ]
      }
    ],
    "evals": [],
    "scaling_policy": [],
    "groups": [
      {
        "ID": "my-spy-app",
        "Scope": [
          "default",
          "example-python"
        ]
      }
    ],
    "images": [
      {
        "ID": "python:3",
        "Scope": [
          "default",
          "example-python",
          "my-spy-app",
          "my-python-task"
        ]
      }
    ],
    "plugins": [
      {
        "ID": "aws-spy-plugin"
      }
    ],
    "deployment": [],
    "volumes": [],
    "allocs": [
      {
        "ID": "example-python.my-spy-app[0]",
        "Scope": [
          "default",
          "48608246-4c28-0446-f3d1-c67e3bc650ad"
        ]
      }
    ]
  },
  "Truncations": {
    "deployment": false,
    "volumes": false,
    "plugins": false,
    "namespaces": false,
    "scaling_policy": false,
    "evals": false,
    "allocs": false,
    "jobs": false,
    "nodes": false
  }
}

Sample Request

$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/search/fuzzy

Prefix matching when fuzzy searching

If the search Context is all when fuzzy searching, the object types that are identified only with UUIDs are also concurrently prefix-searched. Those types include deployments, evals, volumes, and quotas (Enterprise).

Sample Payload (prefix match)

{
   "Text":"cc",
   "Context":"all"
}

Sample Request

$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/search/fuzzy

Sample Result

{
  "Index": 267,
  "KnownLeader": true,
  "LastContact": 0,
  "Matches": {
    "scaling_policy": [],
    "evals": [],
    "deployment": [
      {
        "ID": "cc786388-e071-31ec-5821-b829839f9681"
      }
    ],
    "volumes": []
  },
  "Truncations": {
    "deployment": false,
    "volumes": false,
    "plugins": false,
    "namespaces": false,
    "scaling_policy": false,
    "evals": false,
    "allocs": false,
    "jobs": false,
    "nodes": false
  }
}