Brave Search Goggles Quickstart

Currently, Brave Search does not support applying multiple Goggles simultaneously because instructions from different Goggles might collide in non-intuitive ways.

If you want to use the logic from multiple Goggles, you must create a new Goggle that incorporates the instructions from all your preferred Goggles into a single specification.

Goggles do not apply to the entire Brave Search index. Instead, they are applied to an "expanded recall set," which is a subset of the index determined by the specific input query.

If a specific page is not appearing in your Goggle results, it may be because:

1. The page is not in the expanded recall set for that query.
2. The page is not in the Brave Search index at all.
3. Brave only indexes certain fragments of a page rather than the full content.

When multiple instructions apply to the same result, Brave Search resolves conflicts using a specific hierarchy. The principle is that Goggles are designed to surface content, but explicit removals are final.

Precedence Order (Highest to Lowest):

1. $discard (Final removal)
2. $boost (Any boost strength)
3. $downrank (Any downrank strength)

Specific Strength Rules:

• A higher boost takes precedence over a lower boost (e.g., $boost=3 > $boost=2).
• A higher downrank takes precedence over a lower downrank (e.g., $downrank=2 > $downrank).
• A $boost always takes precedence over a $downrank.

When using Goggles, the Goggle URL is passed along with the search query. Brave treats Goggle URLs with strict privacy provisions, similar to IP addresses or geo-coordinates.

Important Privacy Note: While Brave does not track user queries, if a Goggle is used by only one person or a very small group, the unique Goggle URL could potentially serve as an identifier, allowing for the creation of a profile of that user's queries while they are using that specific Goggle.

Goggles are a set of instructions (rules and filters) that allow individuals or communities to alter the ranking of Brave Search. They act as a custom re-ranking layer on top of the existing Brave Search index.

Key characteristics:

• Customization: Users can create, apply, or extend Goggles to counter intrinsic algorithmic biases or create niche search experiences.
• Ownership: Goggles are owned solely by their creators. If a Goggle is made public, anyone can use it on top of the Brave Search index.
• Functionality: They provide a way to implement custom ranking logic that isn't covered by a general-purpose search engine.

A Goggle is a plain text file containing reranking instructions for Brave Search. To create one:

1. Write the instructions: Use the Goggles DSL to define boosting, downranking, or discarding rules.
2. Add mandatory metadata: Every Goggle must include metadata at the top of the file.
3. Host the file: Upload the text file to a supported platform:
   • GitHub Gists (supports public and secret gists)
   • GitHub (public files only)
   • GitLab (public files and snippets)
4. Submit to Brave: Visit https://search.brave.com/goggles/create and submit your hosted URL. Brave will fetch, validate, and cache it.

Mandatory Metadata Example:

! name: My Goggle
! description: What my Goggle does
! public: false
! author: Me

Updating

To update the instructions, modify your hosted file (e.g., on GitHub) and then resubmit the URL at https://search.brave.com/goggles/create. This triggers a re-fetch of the source.

Deleting

1. Delete the source file at its original hosting URL (GitHub, GitLab, etc.).
2. Trigger the delete in Brave by resubmitting the original URL at https://search.brave.com/goggles/create.

Users can discover Goggles through two primary methods:

1. Direct Links: Any Brave Search link containing a Goggle URL will automatically activate that Goggle. You can follow these Goggles to use them in the future.
2. Discovery Page: Visit https://search.brave.com/goggles/discover to search through existing public Goggles.

A Goggle's identity is tied to its hosting URL. To migrate a Goggle to a new URL without losing followers or popularity statistics, you must use the transferred_to metadata attribute.

Steps to transfer:

1. Add the transferred_to attribute to the original Goggle's specification, pointing to the new hosting URL.
2. Submit the old Goggle to Brave Search again to signify the transfer.

Constraints:

• Both the old and new URLs must be registered Goggles.
• Once a transfer is successful, the old Goggle becomes immutable and cannot be updated further.
• A Goggle can only be transferred once.
• Upon success, all users of the old URL are redirected to the new one.

! name: Original
! description: This is the original Goggle
! author: John
! public: true
! transferred_to: https://gist.github.com/paul/965503febec9a9e917fb816b1ff8820e

To begin building, forking, or extending Goggles, you should follow the Goggles quickstart guide. The process involves learning the Goggles syntax and understanding how to manage the lifecycle of a Goggle (creating, updating, and deleting).

Core tasks include:

• Learning Syntax: Understanding the rules and filters used to define ranking logic.
• Creating/Updating/Deleting: Managing your own Goggles.
• Fine-tuning: Adjusting instructions to improve ranking accuracy.
• Sharing: Making your Goggle public for others to use.

You can customize your Goggle's profile using optional metadata attributes in the header:

• homepage: URL for the homepage displayed on the Goggle's profile.
• issues: URL for reporting issues.
• transferred_to: Allows transferring ownership.
• avatar: A valid HEX color code for the Goggle.
• license: The license governing the instructions.
• public: Set to true to allow discovery on the Brave Goggles discovery page. Set to false to make it private (accessible only via direct URL).

By default, results not matched by your Goggle instructions may still appear if they are highly relevant to the query. To change the 'default action' so that only results explicitly matched by your Goggle are shown, start your file with a generic $discard instruction.

Example (Whitelist approach):

$discard
$boost,site=en.wikipedia.org
$boost,site=de.wikipedia.org

In this example, any result that does not belong to en.wikipedia.org or de.wikipedia.org will be discarded.