All Products
Search

This Product

    DataWorks:Best practices for using Aviator functions as filters

    Document Center

    DataWorks:Best practices for using Aviator functions as filters

    Last Updated:Mar 26, 2026

    In DataService Studio, you can attach Aviator functions to an API as filters — scripts that run before or after the API executes to rewrite request parameters or transform response data.

    Only published Aviator functions can be attached as filters to an API.

    How it works

    Each Aviator function receives its entire input through the default variable $0. The input structure depends on where the function is attached in the API lifecycle:

    Filter position Trigger Input structure
    Prefilter Runs before the API executes Single-layer JSON — the API's request parameters and their values
    Post-filter Runs after the API executes Multi-layer JSON — the full API response

    The function processes $0 and returns the modified object. For a prefilter, the returned value becomes the input to the API. For a post-filter, the returned value is sent back to the API caller.

    Prefilter examples

    A prefilter receives the API's request parameters as a flat JSON object. For example, if the API has a user_id parameter that accepts multiple values:

    {
  "user_id": [0, 1, 2]
}

    Rewrite a parameter value conditionally

    Change user_id from 1 to 2 when the client passes in 1:

    if $0.user_id == 1
{
    $0.user_id = $0.user_id + 1;
}
return $0;

    Input:

    {
    "user_id": 1
}

    Output:

    {
  "user_id": 2
}

    Assign a default value to an empty parameter

    If user_id is optional and the client leaves it blank, set a default value unconditionally:

    $0.user_id = 1;
return $0;

    Input:

    {
    "user_id": ""
}

    Output:

    {
  "user_id": 1
}

    Increment all values in an array parameter

    Traverse the user_id array and increment each element by 1:

    user_id = $0.user_id;
for index in user_id
{
    user_id[index] = index + 1;
}
return $0;

    Input:

    {
  "user_id": [0, 1, 2]
}

    Output:

    {
  "user_id": [
    1,
    2,
    3
  ]
}

    Post-filter examples

    A post-filter receives the full API response as a multi-layer JSON object. The rows array under data contains the returned data entries. For example:

    {
  "data": {
    "totalNum": 3,
    "pageSize": 10,
    "rows": [
      {
        "user_id": 2,
        "city": "BJ",
        "tags": "B,D,dongcs,ccccc"
      },
      {
        "user_id": 3,
        "city": "SH",
        "tags": "A,C,D,F"
      },
      {
        "user_id": 1,
        "city": "HZ",
        "tags": "A,B,C"
      }
    ],
    "pageNum": 1
  },
  "errCode": 0,
  "requestId": "0bb211c516357674333185698eb07b",
  "errMsg": "success",
  "apiLog": null
}

    Modify a field in a specific row

    Find the row where city equals "BJ" and overwrite its tags field:

    rows = $0.data.rows;
for row in rows
{
    if(row.city == "BJ")
    {
        row.tags = "DataService Studio";
    }
}
return $0;

    Input:

    {
  "data": {
    "totalNum": 3,
    "pageSize": 10,
    "rows": [
      {
        "user_id": 2,
        "city": "BJ",
        "tags": "DataService Studio"
      },
      {
        "user_id": 1,
        "city": "HZ",
        "tags": "A,B,C"
      },
      {
        "user_id": 3,
        "city": "SH",
        "tags": "A,C,D,F"
      }
    ],
    "pageNum": 1
  },
  "errCode": 0,
  "requestId": "0bb211e016357705412263266e571e",
  "errMsg": "success",
  "apiLog": null
}

    Output:

    {
  "data": {
    "totalNum": 3,
    "pageSize": 10,
    "rows": [
      {
        "user_id": 2,
        "city": "BJ",
        "tags": "DataService Studio"
      },
      {
        "user_id": 1,
        "city": "HZ",
        "tags": "A,B,C"
      },
      {
        "user_id": 3,
        "city": "SH",
        "tags": "A,C,D,F"
      }
    ],
    "pageNum": 1
  },
  "errCode": 0,
  "requestId": "0bb211e016357705412263266e571e",
  "errMsg": "success"
}

    Add a constant field to every row

    Append is_target = "Y" to each data entry in the rows array:

    rows = $0.data.rows;
for row in rows
{
    row.is_target= "Y";
}

return $0;

    Input:

    {
  "data": {
    "totalNum": 3,
    "pageSize": 10,
    "rows": [
      {
        "user_id": 2,
        "city": "BJ",
        "tags": "DataService Studio"
      },
      {
        "user_id": 1,
        "city": "HZ",
        "tags": "A,B,C"
      },
      {
        "user_id": 3,
        "city": "SH",
        "tags": "A,C,D,F"
      }
    ],
    "pageNum": 1
  },
  "errCode": 0,
  "requestId": "0bb211e016357705412263266e571e",
  "errMsg": "success",
  "apiLog": null
}

    Output:

    {
  "data": {
    "totalNum": 3,
    "pageSize": 10,
    "rows": [
      {
        "is_target": "Y",
        "user_id": 2,
        "city": "BJ",
        "tags": "DataService Studio"
      },
      {
        "is_target": "Y",
        "user_id": 1,
        "city": "HZ",
        "tags": "A,B,C"
      },
      {
        "is_target": "Y",
        "user_id": 3,
        "city": "SH",
        "tags": "A,C,D,F"
      }
    ],
    "pageNum": 1
  },
  "errCode": 0,
  "requestId": "0bb211e016357705412263266e571e",
  "errMsg": "success"
}

    Replace null values across all fields

    When the response contains many fields and you need to replace every null value with a placeholder, use a nested loop. In Aviator syntax, nil is the null constant — equivalent to null in other languages.

    rows = $0.data.rows;
for row in rows
{
    for index in row
    {
        if(index.value == nil)
        {
            index.value = "test"
        }
    }
}
return $0;

    Input:

    {
  "data": {
    "totalNum": 3,
    "pageSize": 10,
    "rows": [
      {
        "user_id": null,
        "city": "SH",
        "tags": "A,C,D,F"
      },
      {
        "user_id": 2,
        "city": "BJ",
        "tags": "DataService Studio"
      },
      {
        "user_id": null,
        "city": null,
        "tags": "A,B,C"
      }
    ],
    "pageNum": 1
  },
  "errCode": 0,
  "requestId": "0bb211f016372870359913841e52d8",
  "errMsg": "success",
  "apiLog": null
}

    Output:

    {
  "data": {
    "totalNum": 3,
    "pageSize": 10,
    "rows": [
      {
        "user_id": "test",
        "city": "SH",
        "tags": "A,C,D,F"
      },
      {
        "user_id": 2,
        "city": "BJ",
        "tags": "DataService Studio"
      },
      {
        "user_id": "test",
        "city": "test",
        "tags": "A,B,C"
      }
    ],
    "pageNum": 1
  },
  "errCode": 0,
  "requestId": "0bb211f016372870359913841e52d8",
  "errMsg": "success"
}

    End-to-end result

    The following shows what happens when you combine a prefilter and a post-filter on the same API. The prefilter assigns user_id = 1 when the client sends an empty value, and the post-filter appends is_target = "Y" to each returned row.

    API input:

    {
  "user_id": ""
}

    API output after both filters run:

    {
  "data": {
    "totalNum": 1,
    "pageSize": 10,
    "rows": [
      {
        "is_target": "Y",
        "user_id": 2,
        "city": "BJ",
        "tags": "DataService Studio"
      }
    ],
    "pageNum": 1
  },
  "errCode": 0,
  "requestId": "0be30a8716357721257118118e2b0f",
  "errMsg": "success"
}

    Filter use effect

    Note

    You can use only a published function as a filter for an API.

    Input and output of the API:

    ## API input:
{
  "user_id": ""
}

## API output:
{
  "data": {
    "totalNum": 1,
    "pageSize": 10,
    "rows": [
      {
        "is_target": "Y",
        "user_id": 2,
        "city": "BJ",
        "tags": "DataService Studio"
      }
    ],
    "pageNum": 1
  },
  "errCode": 0,
  "requestId": "0be30a8716357721257118118e2b0f",
  "errMsg": "success"
}

    What's next