Skip to content

Latest commit

 

History

History
181 lines (133 loc) · 4.07 KB

spec_35.rst

File metadata and controls

181 lines (133 loc) · 4.07 KB
Raw
GitHub is NOT the preferred viewer for this file. Please visit
https://flux-framework.rtfd.io/projects/flux-rfc/en/latest/spec_31.html

35/Constraint Query Syntax

This specification describes a simple string syntax which can be used to succinctly express constraints as described in RFC 31. The syntax may also be useful in generating search and match expressions for use in other parts of Flux.

Name github.com/flux-framework/rfc/spec_35.rst
Editor Mark A. Grondona <[email protected]>
State raw

Language

Related Standards

Goals

  • Describe and define a grammar for a simple text-based string syntax for generating JSON objects in the constraint format defined in RFC 31.

Background

The JSON constraint format described in RFC 31 is not conducive to use on the command line or for other cases where constraints are input by humans. The underlying format has also shown promise as a candidate for use in other search and matching scenarios, for example when filtering jobs. Because of this potential for use throughout Flux, it will be useful to define a simple query syntax which can compile to the more verbose JSON format.

This RFC describes and defines a simple string syntax which can be used by Flux tools and commands to generate RFC 31 compatible JSON constraint objects.

Description

  • A constraint query string is formed by a series of terms.
  • A term has the form operator:operand, where operator: is optional if the implementation defines a default operator. For example, if an implementation defines a default operator of name, then then string myname is equivalent to name:myname.
  • Terms may optionally be joined with boolean operators and parenthesis to allow the formation of more complex constraints or queries.
  • Boolean operators include logical AND (&, &&, or and), logical OR (|, ||, or or), and logical negation (not). The shorthand operators allow terse strings for some implementations e.g. a|b|c.
  • Terms separated by whitespace SHALL be joined with logical AND by default.
  • Quoting of terms SHALL be supported to allow whitespace and other reserved characters in operand, e.g. foo:'this is args'
  • A negation operator is supported in front of terms such that -op:operand is equivalent to not op:operand. Negation MAY NOT be used in front of general expressions, e.g. -(a|b) SHALL be a syntax error.

Grammar

The basic grammar for the constraint query language is

expr
  : expr expr
  | expr and expr
  | expr or expr
  | not expr
  | '(' expr ')'
  | '-' term
  | term

and
  : /&{1,2}|and\b/
or
  : /\|{1,2}|or\b/

not
  : /not\b/

term
  : operator':'operand
  | operand

operator
  : STRING

operand
  : STRING

Examples

The following examples assume a default operator of name

  • foo
{"name": ["foo"]}
  • foo bar
{"and": [{"name": ["foo"]}, {"name": ["bar"]}]}
  • foo bar state:started
{"and": [{"name": ["foo"]}, {"name": ["bar"]}, {"state": ["started"]}]}
  • a|b|c
{"or": [{"name": ["a"]}, {"name": ["b"]}, {"name": ["c"]}]}
  • a|b&c
{"or": [{"name": ["a"]}, {"and": [{"name": ["b"]}, {"name": ["c"]}]}]}
  • (a|b)&c
{"and": [{"or": [{"name": ["a"]}, {"name": ["b"]}]}, {"name": ["c"]}]}
  • (a|-b)&c
{
  "and": [
    {
      "or": [
        {
          "name": [
            "a"
          ]
        },
        {
          "not": [
            {
              "name": [
                "b"
              ]
            }
          ]
        }
      ]
    },
    {
      "name": [
        "c"
      ]
    }
  ]
}