»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.

MethodPathProduces
POST/v1/searchapplication/json

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

Blocking QueriesACL Required
NOnode: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 stanza 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.

MethodPathProduces
POST/v1/search/fuzzyapplication/json

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

Blocking QueriesACL Required
NOnode: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 (groups)

»Scope (tasks)

»Scope (group services)

»Scope (task services)

»Scope (commands/images/classes)

»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)

»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)

»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
  }
}