4,602
edits
Changes
m
* {{icon|repo}} Repository Filters
* {{icon|cite}} Citation Filters
Matches This General filter in the People category will matches people without a known birth date. This rule includes both Persons without any birth-type event and Persons with undated Birth-type events.
====Persons with events matching the <event filter>====
Matches persons who have events that match a certain event filter. Values: Event filter name.
→Ancestor of the default person not more than generations away: specify ”default person” means "Home Person”
{{man index|Gramps 5.1 Wiki Manual - Settings|Gramps 5.1 Wiki Manual - FAQ|5.1}}
{{languages|Gramps_5.1_Wiki_Manual_-_Filters}}
{{#vardefine:chapter|1416}}
{{#vardefine:figure|0}}
[[File:DefineFilter-dialog-default-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} {{man label|[[Gramps_5.1_Wiki_Manual_-_Filters#Define_Filter_dialog|Define filter]]}} - dialog - default]]
Filters allow Gramps to limit operations to a smaller part of a family Tree. The filtered part of the Trees shares a certain characteristic in common. (e.g., females born in France between the years 1550 and 1575.) The filter specifies which characteristics are important and allows choosing values for which to look. (In the example, the Filter looks for People of a particular sex who have an Event in specific Place during a small timespan.) Database queries can be a challenge to compose without errors in syntax. So Filters provide structured and pre-tested database queries that hide most of the syntax complexity while providing some safety nets to avoid routine mistakes. Common characteristics used for filtering are normally presented as "parameter" fields in a form. Then the form composes a properly written query around the parameter. Forms with multiple parameter fields will compound complex queries. Lists of all the filter filtering query rules currently defined in Gramps. Each of these rules is available for use when creating custom filters.
The rules are listed by their [[Gramps_5.1_Wiki_Manual_-_Filters#Which_filters_in_which_Category.3F|categories]].
== Filter vs. Search ==
There are two primary ways to find data in Gramps: Search and Filter. * Search uses the [[Gramps_5.1_Wiki_Manual_-_Main_Window#Search_bar|Search Bar]] above a listing View (such as People, Families, etc). Filter can be used in combination with Search, or stand-alone in the sidebar<br /bottombar Gramplets. >The [[Gramps_5.1_Wiki_Manual_-_Main_Window#Search_bar|Search Bar]] only appears when the entire sidebar is closed. You can show or hide the Gramplet bars through changing the selection of the {{man menu|View ➡ ☑Sidebar}} or {{man menu|View ➡ ☑Bottombar}} menus.* Custom Filters are selected from pop-up menus in the Filter Gramplet, export option and in some reports. They can be used in combination with Search, or stand-alone in the sidebar/bottombar Gramplets. Custom Filters are created or edited from the filter Gramplet or {{man menu|Edit ➡ Filter Editor}} menu. (There is also a basic ''seek-as-you-type'' [[Gramps_5.1_Wiki_Manual_-_Navigation#Finding_records|Find box]] for navigating the active record focus within list view and object selector lists.)
{{man note|Name filtering behavior has [[Rule_expansions#Gramps_5.1.0_.28Aug._2019.29|changed for Gramps 5.1]]|In prior versions of Gramps, the name portion of the Filter Gramplet would try to match on any single name field (given, surname, prefix, etc) of all names (primary and alternate) but only field per name — you couldn't match the given field and surname field in the same name. You could match surname, but simultaneously matching surname and given in the same query wasn't possible. For example, if you Filter on "John", you would get matches of people with firstname "John" but also those with surname "Johnson". More complex search required use of the regular expressions pattern matching options or custom filters.<br /><br />This constraint has been removed and simultaneous search of multiple terms is now the default behavior.}}
Search and Filter work completely differently and it is useful to understand these differences:
* The Filter allows "regular expressions". So you can find all of the names that start with "B" and end in "ship": "B.*ship". You can't do that with the [[Gramps_5.1_Wiki_Manual_-_Main_Window#Search_bar|Search Bar]].
* The Search will only match what is visible. If a name or text is too big to see in listing below [[Gramps_5.1_Wiki_Manual_-_Main_Window#Search_bar|Search Bar]], then you won't find it. This is something to keep in mind when Searching through Notes. Best to use Filter for notes and other long text fields.
* All Filters default to use case-insensitive matching; "Ship" will match "ship", "SHIP", or "ShIp". As explained below under Regular Expressions, using Regular Expressions does not currently give a means of changing from the default.
=== See also ===
* [[Rule expansions|Expanding the Filter rulebook]] with Addons
* [[:Category:Filters|Category: Filters]]
* [[Template:Backup Omissions|Custom Filter migration]] - backing up a Gramps Tree does not back up your filters.include any filter customizations
{{-}}
== Regular Expressions ==
[https://en.wikipedia.org/wiki/Regular_expression Regular Expressions](aka ''regex'', ''regexp'', or sometimes ''rational expression'') are a quick condensed, precise and powerful way to describe text that matches a pattern. Gramps uses Designing a effective search pattern can be formulaic. Like math formulas, a search pattern can be quickly composed which finds a subset of records but does so very crudely and slowly. Elegant and efficient RegEx as a matching option phrases are collected by optimization experts in Filtersdata manipulations. There are many resources (books, websites, professional training) for RegEx design and strategy.
Gramps uses RegEx as a matching option that may be enabled for Custom Filters and in the Filter Gramplets of each Category view. RegEx pattern matching is an advanced feature that and so its checkbox is disabled not selected by default. For Custom Filters, each individual Rule has a {{checkbox|1}}{{man label|Use regular expressions}} option check box in its Edit Rule dialog. The Filter Gramplets also have {{checkbox|1}}{{man label|Use regular expressions}} option check boxes to allow regexp expression to be used directly for matching strings in their text boxes.
For example, if you were looking for a surname that started with a "B", and ended with "ship" then you could use regular expressions to describe that pattern. That would be '''<code>^B.*ship</code>''':
* The '''<code>ship</code>''' matches the exact letters s, h, i, p in that order.
Regular expressions are quite powerful, and there are many options. We use the [https://docs.python.org/3/library/re.html Python Regular Expression ] system, and we will document that here. In addition, you can use any Python Regular Expression resource. Gramps is currently implemented to make all string matching case-insensitive (which is the opposite of the usual default in Python). There is no easy way at present to override this behaviour for the relatively uncommon purpose of matching strings that have been entered into the database in a particular case format. Regular expressions in Gramps currently give identical results regardless of whether the target string is entered in upper case, title case, lower case or some mixture.
''whitespace'' - The term "whitespace" is used below to mean one or more character that you don't see. For example, whitespace includes tabs, spaces, and newlines.
There are some characters that have special meaning with regular expressions. They are:
* '''<code>. ^ $ * + ? { } [ ] \ | ( )</code>'''<br/>decimal point (full stop), caret, dollar sign, asterisk, plus sign, question mark, left and right curly braces, left and right square brackets, backslash, vertical bar (pipe), left and right parentheses
They can be used as described:
{{Man warn|Regular Expression 'dialect' noted and Repaired|In Gramps 5.1, the sidebar filter inappropriately evaluated parameters containing spaces... attempting to re-interpret a single Regular Expression as a sequence of separate expressions. The Gramps 5.1.1 resolution for Bug {{Bug|0011321}} handles Regular Expressions more literally.}}
=== See Also ===
Regular expressions have been in wide use across the computer industry since the 1950s. But they are "expert tools" designed for power and efficiency rather than intuitiveness. As a result, many resources have been developed on the web.
Some of these resources have excellent tutorials. Some have cheat sheets. Some have “sand boxes” where regular expressions can be explored in real-time.
A sampling of RegEx reference websites:
* [http://rexegg.com/ rexegg.com] (tutorials)
* [https://www.regular-expressions.info/ RegexBuddy]
* [https://regex101.com/ regex101.com] (sandbox with feedback)
==Custom Filters==
{{man tip|Custom Filter migration|Keep your collection of custom filters through a minor updates of Gramps (e.g., from version 5.0.x to 5.1.x) by manually copying your ''custom_filter.xml'' from [[Gramps User Directory]] to the corresponding directory in new ''gramps_version_number''. <br /><br />Even minor upgrades (e.g., from a 5.0.x to a 5.1.x version) may include format changes since the recent innovation of add-on addon rules are causing rapid evolution in Filters. So porting filters in this manner requires verification that the XML definitions haven't changed. Also, Add-on Addon rules may have to be installed in the new upgrade before copied custom filters will work safely.}}
You can carry out a considerable amount of selection of persons, events, places, etc., just using the Filter Sidebar in Person, Event, Place,etc. Views; but note, however, that the 'Use regular expressions' option '''only works with particular fields''' in each View.
If the Filter Sidebar is inadequate for your purpose, you will need to build custom filters.
{{man tip|Building a quick Custom Filter for an object|The clipboard has a Custom Filter generation shortcut. Copy any View object to the Clipboard (by drag'n'drop or by selecting and pressing the {{man key press|Ctrl|C}} [[Gramps_5.1_Wiki_Manual_-_Keybindings|keybinding]]), then select the object on the Clipboard and right-click to reveal the [[Gramps_5.1_Wiki_Manual_-_Navigation#Clipboard_context_menu|Clipboard's contextual pop-up menu]]. The bottom menu item will offer to create a Filter for the selected object.}}
===CategoryName Filters dialog===
* {{icon|plac}} Place Filters
* {{icon|sour34}} Source Filters
* {{icon|cite}} Citation Filters
* {{icon|repo}} Repository Filters
* {{icon|medi}} Media Filters
* {{icon|note}} Note Filters
When in the {{man label|''CategoryName'' Filters}} dialog you have the following options from the right hand side icons:
===Define Filter dialog===
{{man tip|Add-on Addon Rules for custom filters are available|Filter Rules can be expanded through the addons interface starting with the Gramps 5.1.0 version.<br />''See: '''[[Example filters]]''' and '''[[Rule_expansions|Add-On Addon Rules]]'''''}}
[[File:DefineFilter-dialog-default-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Define filter - dialog - default]]
===Add Rule dialog===
{{man tip| A filter you have already designed may be used as a rule parameter for another filter.|This gives you nearly infinite flexibility in custom-tailoring your selection criteria that can be later used in most of the exports, reports, and some of the tools (such as comparing individual events).<br />''See: '''[[Example filters]]''' and '''[[Rule_expansions|Add-On Addon Rules]]'''''}}
[[File:AddRule-selector-dialog-PersonFilters-example-50.png|right|thumb|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Add Rule - selector dialog - available for Person filters - example]]
* Click on the {{man button|▶}} arrows to fold/unfold the appropriate category.
* Select the rule from the tree by clicking on its name. The right-hand side displays the name, the description, and the values for the currently selected rule.
{{man tip|Finding a rule|It can be hard to remember which filter grouping contains a rule. And, since the "[[Rule_expansions|add-on addon rule]]" is a recent innovation, there can be too many rules to peruse easily. So you can narrow down the rule list -- based on keywords from the rule titles.<br /><br />Type a keyword by using the search box (box with the magnifying glass) and only the groupings with matches will be expanded.}}
Once you are satisfied with your rule selection and its values, click {{man button|OK}} to add this rule to the rule list of the currently edited filter. Clicking {{man button|Cancel}} will abort adding the rule to the filter.
<span id="Which filters in which Category?">
== Which filter rules in which Category? ==
===Ancestor of the default person not more than <N> generations away===
The ”default person” is the individual that has been defined as the ”Home Person”. (The ”default” is a legacy term in Gramps that caused minor confusion she nice the word is used in so many different parts of the wiki to describe different things.)
{{stub}}
====People with the personal <event>====
This rule matches people that have a personal event matching specified values for the Event type, Date, Place, and Description. The rule returns a match even if the person's event matches the value partially. The matching rules are case-insensitive. For example, anyone who graduated in Sweden will be matched by the rule using the Graduation event and the value "sw" for the Place. The personal events should be selected from a pull-down menu. The rule returns a match if, and only if, all non-empty values are (partially) matched by the personal event. To use just one value, leave the other values empty.
====Persons with events matching the <event filter>====
Matches persons who have events that match a certain event filter. Values: Event filter name.
====Witnesses====
This rule matches adopted people.
===Child Children of <filter> match===
This rule matches people for whom either parent is matched by the specified filter. The specified filter name should be selected from the menu.
====People with the personal <attribute>====
Matches people with the personal attribute of a particular value. Use RegEx pattern matching to search for [[Gramps_5.1_Wiki_Manual_-_Filters#regex_all|all values]] or attributes that have been [[Gramps_5.1_Wiki_Manual_-_Filters#regex_null|left blank]]. Values: Family Personal Attribute: Identification Number -- Age ...
====People with unknown gender====
====People without a known birth date====
====People without a known death date====
Equivalent rules exist for records of the corresponding category type in People, Families, Events, Places, Sources, Citations, Repositories, Media, and Notes category views.
====Soundex match of People with the <name>====
====Media objects marked private====
Matches media objects that are indicated as private.
====Media objects matching parameters====
{{stub}}
====Media objects matching the <filter>====
<!-- merge with above? -->
Due to the '''static''' nature of tags, it might be useful to add a tag to a selection of objects. For example one should be able to select a number of person in the [[Gramps_5.1_Wiki_Manual_-_Main_Window_Categories#People_Category|Person View]], and add them a new tag or an existing one.
{{-}}
===Organize Tags Window===
* [[Tags in Gramps]] - an introduction
* Automatic [[Gramps_5.1_Wiki_Manual_-_Settings#General_Gramps_settings|Import timestamp Tags]]
* filtered [[Addon:RemoveTagTool|Add/Remove Tag Tool]] (Third party add-on addon for Gramps)
