FD1 Query Selector Options

The "q" parameter allows you to query a subset of rows from the endpoint. Not all endpoints honour "q", but the majority do.

Some quick examples to start:

{
    a: "fd1.data",
    q: {
        "rve(>)": 20260113.135466,
        "description(like)": "bob"
    },
    v: {
        table: "logical.products"
    }
}

{
    a: "fd1.data",
    q: {
        "department": [2,3,4],
        "spid": 8
    },
    v: {
        table: "logical.products"
    }
}

{
    a: "fd1.data",
    q: {
        "email(like,typed)": "ruth@gamil.com"
    },
    v: {
        table: "logical.customers"
    }
}

q "Query" Object

Some endpoints use a "q" object to query, select or restrict the data to be accessed. In SQL terminology this would be the "where" clause

1. Any Field name that starts with an underscore has special meaning
2. Any field that starts with a letter is a reference to column in the data
3. If a field name is used in isolation (eg "id": 123 ) then this means id=value
4. If a field name includes a bracket reference at the end, (eg "id(gt)": 4041 means id > 4041 ) then this defines the requested predicate check. Endpoints can block predicate types if they wish, do not assume that you can use different predicates on every field
5. Predicate checks contain many of the standard checks you would expect, =,<,>,like and also some advanced ones such as
   like.words - search for words in any order
   bitnset - test if a specific bit is set.
6. Predicate checks can contain modifiers to provide hints, description(like,typed):"bob" means perform a like operation for "bob", where bob was typed by the user.
   sku(=,voice):"PLZ123" - search "sku" for exact match of "PLZ123". The PLZ123 was captured by voice, so the engine may choose to search for common verbal variations.
   or sku(=,ocr):"B0B" - search sku for B-zero-B. The engine may choose to also search for B-Oh-B as well, as 0/O confusion can occur with OCR engines.

   Using modifers implies that you are wanting to receive "near matches" in the results. If you only want exact match, do not add modifiers.

7. When q requests are processed, the engine may output warnings as "warn" packets on the output.

Modifiers

A modifer can be applied to a predicate to indicate processing hints. The server is free to ignore modifiers. Modifiers allow the server to make small obvious changes to the value, but exact matches to the provided value take priority for the returned result. In the first example below, if the name "bpb" and "bob" both exist, "bpb" will be returned, not "bob". "bob" can only be returned if there is no "bpb"

Q Warnings

The q engine can feedback issues by outputting a series of "warn" objects on the output.

{
    q: {
        id_number: "abc",
        short_code: "zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz23"
    }
}

{
    data: {
        rows: []
    },
    warn: [
        {
            area: "q",
            key: "id_number",
            message: "id_number can only be digits, result is therefore empty array"
        },
        {
            area: "q",
            key: "short_code",
            message: "Short_code is defined by site policy to be maximum 12 characters, the input is longer than that so no rows can possibly match"
        }
    ]
}

{
    a: "FD1 endpoint to read products"
    q: {
        "description(like)": "en",
        "depid(in)": [3,4,5],
        "price(ge)": 100,
        "price(lt)": 2500
    }
}

Reserved Field Names

_search

This keyword causes the engine to scan the entire row for "value". It is intended primarily for user facing search. Not all fields will be searched and the server decides which fields should be checked. Some site specific selection may be possible for some tables.

• A search such as _search(typed): "unsub" will select which fields to search dynamically. In this case, the "email" field will not be searched as there is no "@". Even if the email field contains exactly "unsub", it is unlikely to be searched, as emails require "@", and we do not support storing non standard data into fields.
• The search _search(typed): "no email" may choose to select only rows where email is either blank or invalid, but will eliminate rows with probably valid emails.
• _search will always at least perform a like style operation on key description style fields.
• You can use other predicates as well as search, the following applies a generic search, but only on the subset of products from supplier Acme

  {
      q: {
          supplier: "acme",
          "_search(typed)": "water based paint in stock"
      }
  }