More on filters

In Defining your first filter, you added a new filter to a table by using the AddNew method of the Table.Filters collection. You typically create filters in this way when you want to specify a filter for use in a specific table. However, you might want to use the same filter for more than one table.

If you want to use the same filter on several tables, you can define the filter as a table document filter. You do this by creating it in the Document.Filters collection. The filter is then available to add to any table in the document. The following example creates a table document filter variable called Exclude11_16s and uses it on a specific table:

TableDoc.Filters.AddNew("Exclude11_16s", "Not age.ContainsAny({e1116_years})")
TableDoc.Tables.AddNew("Table1", "age * gender")
TableDoc.Tables[0].Filters.Add("Exclude11_16s")

This example uses the Filters.Add method to add the filter to the table. You use this method to add a filter that has already been defined in the Document.Filters collection.

When you create a filter in this way, you must explicitly add it to each table. To add the same filter to all of your tables, define the filter as a global filter: create the filter in the Document.Global.Filters collection. The filter is then applied to all of the tables. If any of the tables already have a filter, the And operator is used to combine the global filter with the existing filters. Here is an example of creating a global filter:

To add the same filter to some but not all of your tables, use the Document.Default.Filters collection. Handling zero values and setting hide rules shows that when you change the value of the table document’s default ZeroValueSymbol property, it does not affect tables that had already been created. Setting up a default filter works in a similar way.

Default filters are useful when, for example, you want to create two sets of tables, one of which is filtered on men and the other on women. For example:

' Create a new default filter
TableDoc.Default.Filters.AddNew("Females", "gender = {female}")

' Create the second table
TableDoc.Tables.AddNew("Table2", "age * gender")

' Remove the Females default filter and create a new Males default filter
TableDoc.Default.Filters.Remove("Females")
TableDoc.Default.Filters.AddNew("Males", "gender = {male}")

' Create the third table
TableDoc.Tables.AddNew("Table3", "age * gender")

When you create a filter using the Table Object Model, it is saved with the table document, but is not available to other table documents that use the same data set. To create filters that become “permanently” part of a data set, set them up as Boolean variables in the metadata. For more information, see Example 3: Creating filter variables.