> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usedatabrain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Metric App Filter

> Metric App Filter: Instruction Manual

Using the App Filter in Metric:

<Steps>
  <Step title="Create a Metric Filter">
    * In your Metric, create a new filter
    * In the "Apply On" section, enable the "App Filter" option

    <Frame>
      <img src="https://mintcdn.com/databrainlabs-bef6850a/4wZlBKZskJWgCs2c/images/developer-docs/create-metric-filter.png?fit=max&auto=format&n=4wZlBKZskJWgCs2c&q=85&s=1b1b8f6c07ba3b5daa5598667b57216a" alt="Metric filter configuration with App Filter enabled" width="512" height="409" data-path="images/developer-docs/create-metric-filter.png" />
    </Frame>
  </Step>

  <Step title="Passing Filter Values">
    ### Method 1: Passing from Component

    * Use the parameter `"metric-filter-options"` to pass values directly from a component to the metric filter.
    * Configuration changes based on the Filter Type and the Data Type.

    1. **Single-Select Filter:**
       * For *string-based* filters, pass just the value:

    ```javascript theme={"dark"}
    metric-filter-options={JSON.stringify({   // note that invalid options will be filtered out
      "Filter name for a string datatype": {
        options: [
                    { value: 'James Smith', label: 'James' },
                    { value: 'Olivia Johnson', label: 'Olivia' },
                    { value: 'Emma Brown', label: 'Emma' },
                  ] // should have unique elements
        defaultOption: 'James Smith', // value of the selected option
      },
      "Filter name for a number datatype": {
        options: [{ value: 1, label: 'user_1' }, { value: 2, label: 'user_2' }], // should have unique elements
        defaultOption: 1, // value of the selected option
      },

    ```

    2. **Multi-Select Filter:**
       * For *string-based* filters, pass an array of values:

    ```javascript theme={"dark"}
    metric-filter-options={JSON.stringify({ // note that invalid options will be filtered out
      "Filter name for a string datatype": {
        options: [
                    { value: 'James Smith', label: 'James' },
                    { value: 'Olivia Johnson', label: 'Olivia' },
                    { value: 'Emma Brown', label: 'Emma' },
                  ] // should have unique elements
        defaultOption: ['James Smith', 'Olivia Johnson' ], // value of the selected option
      },
      "Filter name for a number datatype": {
        options: [{ value: 1, label: 'user_1' }, { value: 2, label: 'user_2' }], // should have unique elements
        defaultOption: 1, // value of the selected option
      },
    ```

    Refer the below “Options” document for further queries.

    <Card title="Options" icon="check" href="https://docs.usedatabrain.com/developer-docs/helpers/options" />

    ***

    ### Method 2: Passing from Guest Token

    * You can link a guest token here to pass the filter values dynamically.\
      Refer the below document to generate a guest token.

    <Card title="Options" icon="check" href="https://docs.usedatabrain.com/developer-docs/token" />

    ```json theme={"dark"}
    {
      "clientId": "id",
      "workspaceName": "workspacename",
      "params" : {
         "appFilters": [{
    			“metricId”: “The id of the metric you want to have app filters”,
    			“values”: {
    				“paid_orders”: true,
    				“amount”: 500,
    				“country”: ["USA", "CANADA"] || "USA" // based on filter variant(select or multi select)
    			}
    		}]
       }
    }

    ```

    ***

    ### Method 3: Handling Large Selections with SQL Integration

    Filters with a large number of options (e.g., over 500), manually passing all values becomes inefficient. With SQL integration, you can dynamically fetch options from your database, simplifying the process.

    The SQL query specified under the `<InlineCode>"sql"</InlineCode>` key dynamically fetches the latest values from the specified database table.

    ```json theme={"dark"}
    {
      "clientId": "id", 
      "workspaceName": "workspacename",
      "params": {
        "appFilters": [
          {
            "metricId": "The id of the metric you want to have app filters",
            "values": {
              "paid_orders": true,
              "amount": 500,
              "country": {
                "sql": "SELECT \"name\" FROM \"public\".\"countries\" WHERE isEnabled=true",
                "columnName": "name"
              }
            }
          }
        ]
      }
    }

    ```

    #### Key Benefits:

    1. **Dynamic Updates:** The SQL query retrieves only the latest relevant options from your database.
       * Example: `SELECT "name" FROM "public"."countries" WHERE isEnabled=true` fetches active country names.
    2. **Efficiency:** Eliminates the need to manually manage large datasets in the configuration.
    3. **Flexibility:** The `columnName` specifies the field in the query result to use as filter values.
    4. **Scalability:** Handles thousands of options seamlessly, reducing payload size and improving performance.

    This approach is ideal for keeping filters updated with minimal effort, ensuring they remain efficient and user-friendly.
  </Step>
</Steps>