External Filtering

Simple Mode (recommended)

External filtering allows you to define specific query conditions via an input. To use external filtering, you need to construct a JSON array defining the conditions of the search in the following format.

{
  "expression": [
    {
      "statement": {
        "left": {
          "tag": "col",
          "operand": ""
        },
        "op": "==",
        "right": {
          "operand": ""
        }
      }
    }
  ]
}

In this example, we are doing a simple search to check if a field contains a specific value. The left, op, and right values match exactly what we would see in the Query All Records expression builder. See this reference for a list of the operators available and what they mean.

If you want to define multiple search conditions, you can add additional objects to the "expression" array.

Video Example of External Filtering (Simple Mode)

External Filtering - Additional JSON Examples

GET users with the email [e-mail]:

{
  "external": {
    "expression": [{
      "statement": {
        "left": {
          "tag": "col",
          "operand": "user.email"
        },
        "right": {
          "operand": "[e-mail]"
        }
      }
    }]
  }
}

GET users with a score great than 10:

{
  "external": {
    "expression": [{
      "statement": {
        "left": {
          "tag": "col",
          "operand": "user.score"
        },
        "op": ">",
        "right": {
          "operand": 10
        }
      }
    }]
  }
}

GET users with the email [e-mail] AND a score greater than 10:

{
  "external": {
      "expression": [{
        "statement": {
          "left": {
            "tag": "col",
            "operand": "user.email"
          },
          "right": {
            "operand": "[e-mail]"
          }
        }
      }, {
        "statement": {
          "left": {
            "tag": "col",
            "operand": "user.score"
          },
          "op": ">",
          "right": {
            "operand": 10
          }
        }
      }]
  }
}

GET users with the email [e-mail] OR a score greater than 10:

{
  "external": {
      "expression": [{
        "statement": {
          "left": {
            "tag": "col",
            "operand": "user.email"
          },
          "right": {
            "operand": "[e-mail]"
          }
        }
      }, {
        "or": true,
        "statement": {
          "left": {
            "tag": "col",
            "operand": "user.score"
          },
          "op": ">",
          "right": {
            "operand": 10
          }
        }
      }]
    }
  }

GET users with the email [e-mail] AND a score greater than 10 or less than 5:

{
  "external": {
    "expression": [{
      "statement": {
        "left": {
          "tag": "col",
          "operand": "user.email"
        },
        "right": {
          "operand": "[e-mail]"
        }
      }
    }, {
      "type": "group",
      "group": {
        "expression": [{
          "statement": {
            "left": {
              "tag": "col",
              "operand": "user.score"
            },
            "op": ">",
            "right": {
              "operand": 10
            }
          }
        }, {
          "or": true,
          "statement": {
            "left": {
              "tag": "col",
              "operand": "user.score"
            },
            "op": "<",
            "right": {
              "operand": 5
            }
          }
        }]
      }
    }]
  }
}

Classic Mode (deprecated)

How do I use the external query to allow filtering additions?

First, create an input that is a JSON data type.

In this example, the input named "external" was added and is a JSON data type.

Next, link the configuration in the External query tab to the JSON input using the drop down menu. Additionally, select "Allow Filtering Additions" permission.

In this example, under the External tab of the Query all Records function, we linked up the input "external" for external filtering. Additionally, we selected the permission to Allow Filter Additions.

Now, we are ready to use the filter by external query. Because the external query takes a JSON input, we must format the input in a JSON like the examples below.

GET users with the email [e-mail]:

{
  "external": {
    "expression": [{
      "statement": {
        "left": {
          "tag": "col",
          "operand": "user.email"
        },
        "right": {
          "operand": "[e-mail]"
        }
      }
    }]
  }
}

In this example, the code block above is pasted into the Run & Debug. This will filter by users with the email address "[e-mail]."

GET users with a score greater than 10:

{
  "external": {
    "expression": [{
      "statement": {
        "left": {
          "tag": "col",
          "operand": "user.score"
        },
        "op": ">",
        "right": {
          "operand": 10
        }
      }
    }]
  }
}

GET users with the email [e-mail] AND a score greater than 10:

{
  "external": {
      "expression": [{
        "statement": {
          "left": {
            "tag": "col",
            "operand": "user.email"
          },
          "right": {
            "operand": "[e-mail]"
          }
        }
      }, {
        "statement": {
          "left": {
            "tag": "col",
            "operand": "user.score"
          },
          "op": ">",
          "right": {
            "operand": 10
          }
        }
      }]
  }
}

GET users with the email [e-mail] OR a score greater than 10:

{
  "external": {
      "expression": [{
        "statement": {
          "left": {
            "tag": "col",
            "operand": "user.email"
          },
          "right": {
            "operand": "[e-mail]"
          }
        }
      }, {
        "or": true,
        "statement": {
          "left": {
            "tag": "col",
            "operand": "user.score"
          },
          "op": ">",
          "right": {
            "operand": 10
          }
        }
      }]
    }
  }

GET users with the email [e-mail] AND a score greater than 10 or less than 5:

{
  "external": {
    "expression": [{
      "statement": {
        "left": {
          "tag": "col",
          "operand": "user.email"
        },
        "right": {
          "operand": "[e-mail]"
        }
      }
    }, {
      "type": "group",
      "group": {
        "expression": [{
          "statement": {
            "left": {
              "tag": "col",
              "operand": "user.score"
            },
            "op": ">",
            "right": {
              "operand": 10
            }
          }
        }, {
          "or": true,
          "statement": {
            "left": {
              "tag": "col",
              "operand": "user.score"
            },
            "op": "<",
            "right": {
              "operand": 5
            }
          }
        }]
      }
    }]
  }
}

Need an alternative to the JSON input due to front-end limitations?

See the example from external sorting.