Skip to content

Instantly share code, notes, and snippets.

@turboBasic

turboBasic/firefox-places-query.md

Last active November 8, 2021 06:56
Show Gist options
  • Save turboBasic/d2ae1ca0e7b67e648b65ccc0900f201d to your computer and use it in GitHub Desktop.
Save turboBasic/d2ae1ca0e7b67e648b65ccc0900f201d to your computer and use it in GitHub Desktop.
Download ZIP
Firefox bookmarks with queries to Places db #firefox
Raw
firefox-places-query.md

Firefox Places database queries

Summary

  • For bookmark queries term is searched within bookmark names and tags. Title is returned if it contains term, tag is returned if only it matches term completely.

Examples

Bookmarks queries

  • all bookmarks in Bookmarks Toolbar tagged with tag groovy, queries are expanded

    place:queryType=1&expandQueries=true&parent=toolbar_____&tag=groovy

  • all bookmarks in Bookmarks Toolbar tagged with tag jenkins

    place:queryType=1&parent=toolbar_____&tag=jenkins

  • 20 most visited bookmarks
    not history items but currently bookmarked items only

    place:queryType=1&sort=8&maxResults=20

  • 10 last bookmarked items

    place:folder=2&folder=3&folder=5&queryType=1&sort=12&excludeItemIfParentHasAnnotation=livemark%2FfeedURI&maxResults=10&excludeQueries=1

History queries

  • 20 most visited URLs, only bookmarked.
    (compare with similar example from previous section. Results are page titles whereas previous query returns bookmark names)

    place:queryType=0&sort=8&maxResults=20&onlyBookmarked=true

  • 10 most visited URLs with word example

    place:queryType=0&sort=8&maxResults=10&terms=example

  • 5 most visited URLs in google.com domain

    place:queryType=0&sort=8&maxResults=5&domain=google.com

  • history items satisfying all following conditions:
    - firefox in page title
    - from mozilla.org domain
    - visited less than 24 hours ago

    place:queryType=0&beginTime=-86400000000&endTime=0&domain=mozilla.org&terms=firefox

    0 is now, 86˙400˙000˙000 is 24 hours * 60 minutes * 60 seconds * 1˙000˙000

Tag queries

  • 10 recent tags sorted by last modified date

    place:type=6&sort=14&maxResults=10

References

Query parameters

Tell what to search. All parameters are ANDed together.

  • annotation - (String) Annotation to match. Values: Any

  • !annotation - (Boolean) Test for existance or non-existance of a given annotation. "Annotation is not". Values:
    - true: Remove everything that doesn't have annotation.
    - false: Normal results

  • beginTime - (Unsigned Long) Time range for results. Lower boundary.
    Time format is in microseconds, so multiply with 1000000 * 60 * 60 for hours and for days multiply that with 24.

  • beginTimeRef - (Unsigned Long) Indicates how to interpret the corresponding time value in beginTime. Values:
    - 0: (default) - The time is relative to Jan 1 1970 GMT
    - 1: The time is relative to this morning at midnight. Normally used for queries relative to today
    - 2: The time is relative to right now

  • endTime - (Unsigned Long) Time range for results. Upper boundary.

  • endTimeRef - (Unsigned Long) Indicates how to interpret the corresponding time value in endTime.

  • domain - (String) Query for this host or domain name (controlled by domainIsHost). Values: Any

  • domainIsHost - Controls the meaning of domain, and whether it is an exact match (true), or hierarchical (false) which returns anything whose host name ends with domain.

  • folder - Folder that is queried. Values:
    - PLACES_ROOT: Places Root Folder
    - BOOKMARKS_MENU: Bookmarks Menu
    - TOOLBAR: Bookmarks Toolbar
    - TAGS: Tags
    - UNFILED_BOOKMARKS: Unfiled Bookmarks

  • minVisits - (Long) Filter results based on number of visits. This is lower value. Values:
    - -1 (default): Show all
    - Any: Show items with visit count larger than this number.

  • maxVisits - (Long) Filter results based on number of visits. This is upper value. Values:
    - -1: (default) Show all
    - Any: Show items with visit count smaller than this number.

  • onlyBookmarked - (Boolean) Return only bookmarked items. Values:
    - true: Return only bookmarked items
    - false: Return all

  • terms - (String) Query this term. Values: Any

  • uri - URI to match. Values: Any

  • uriIsPrefix - Controls the interpretation of uri. When unset (default), the URI will request an exact match of the specified URI. When set, any history entry beginning in uri will match. For example http://bar.com/foo will match http://bar.com/foo as well as http://bar.com/foo/baz.gif.

Query configuration

Tell how to search. Modifies behavior of query.

  • excludeItems - Excludes all URIs and separators from a bookmarks query. This would be used if you just wanted a list of bookmark folders and queries (such as the left pane of the places page). Ignored for queries over history. Defaults to false.

  • excludeQueries - Set to true to exclude queries (place: URIs) from the query results. Simple folder queries (bookmark folder symlinks) will still be included. Defaults to false.

  • excludeReadOnlyFolders - Set to true to exclude read-only folders from the query results. This is designed for cases where you want to give the user the option of filing something into a list of folders. It only affects cases where the actual folder result node would appear in its parent folder and filters it out. It doesn't affect the query at all, and doesn't affect more complex queries (such as folders with annotation X).

  • excludeItemIfParentHasAnnotation - This option excludes items from a bookmarks query if the parent of the item has this annotation. An example is to exclude livemark items (parent folders have the livemark/feedURI annotation). Ignored for queries over history.

  • expandQueries - When set, allows items with place: URIs to appear as containers, with the container's contents filled in from the stored query. If not set, these will appear as normal items. Doesn't do anything if excludeQueries is set. Defaults to false. Note that this has no effect on folder links, which are place: URIs returned by nsINavBookmarkService.GetFolderURI. These are always expanded and will appear as bookmark folders.

  • includeHidden - Most items in history are marked as hidden. Only toplevel pages that the user sees in the URL bar are not hidden. Hidden things include the content of iframes and all images on web pages. Normally, you don't want these things. If you do, set this flag and you'll get all items, even hidden ones. Does nothing for bookmark queries. Defaults to false.

  • maxResults - Set max number of results to return. Note: the query is executed, the results are sorted, and then the top maxResults results are taken and returned. Set to 0 (the default) to get all results.
    THIS DOES NOT WORK IN CONJUNCTION WITH SORTING BY TITLE. This is because sorting by title requires us to sort after using locale-sensitive sorting (as opposed to letting the database do it for us). Instead, we get the result ordered by date, pick the maxResult most recent ones, and THEN sort by title.

  • OR - Change behavior of composition of query search parameters from AND to OR

  • originalTitle - Retrieves original page title. Not searchable?

  • queryType - (Unsigned Short) The type of search to use when querying the DB; This attribute is only honored by query nodes. It is silently ignored for simple folder queries. Values:
    - 0: History
    - 1: Bookmarks
    - 2: Unified

  • showSessions - Separate/group history items based on session information. Only matters when sorting by date.

  • sort - (Unsigned Short) Sort results. Values:
    - 0: Natural bookmark order
    - 1: Sort by title, A-Z
    - 2: Sort by title, Z-A
    - 3: Sort by visit date, most recent last
    - 4: Sort by visit date, most recent first
    - 5: Sort by uri, A-Z
    - 6: Sort by uri, Z-A
    - 7: Sort by visit count, ascending
    - 8: Sort by visit count, descending
    - 9: Sort by keyword, A-Z
    - 10: Sort by keyword, Z-A
    - 11: Sort by date added, most recent last
    - 12: Sort by date added, most recent first
    - 13: Sort by last modified date, most recent last
    - 14: Sort by last modified date, most recent first
    - 17: Sort by tags, ascending
    - 18: Sort by tags, descending
    - 19: Sort by annotation, ascending
    - 20: Sort by annotation, descending

  • type - (Unsigned Short) Type of results that are returned. Values:
    - 0: Results as URI (URI results, one for each URI visited in the range).
    - 1: Results as visit (visit results, with one for each time a page was visited - this will often give you multiple results for one URI).
    - 2: Results as full visits (like visit, but returns all attributes for each result)
    - 3: Results as date query (returns results for given date range)
    - 4: Results as site query (returns last visit for each url in the given host)
    - 5: Results as date+site query (returns list of hosts visited in the given period)
    - 6: Results as tag query (returns list of bookmarks with the given tag)
    - 7: Results as tag container (returns bookmarks with given tag - for same uri uses last modified). folder=tag_folder_id must be present in the query.

TODO Process not-formatted items

Folder GUIDs

  • root________
  • menu________
  • toolbar_____
  • tags________
  • unfiled_____
  • mobile______

Sources

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment