Search Cookbook

1. Textual constraints
2. Language constraints
   • Searching with multiple languages at the same time
3. Schema constraints
4. Metaschema constraints
   • Supported Metaschema filter operands
5. Scoring and ranking
6. Other constraints

This page contains a list of recipes for different ways to constrain search queries using the Search Service.

Textual constraints

Textual data for a Freebase entity comes first from its name and its aliases, then from its keys and other textual properties, and finally from its Wikipedia anchor data if it was reconciled with a language-specific Wikipedia topic.

Textual constraints are language-specific; currently, 18 languages are supported. English has by far the most coverage and is the default language.

For a list of all currently supported language codes, visit the following:

https://www.googleapis.com/freebase/v1/search?help=langs&indent=true

A textual constraint is specified with the query parameter. Its language is specified with the lang parameter. For example:

query: "gore"
query: "gore" lang: "fr"
query: "gore" lang: "de"

During indexing, textual data is normalized in a language-specific way. For example, in English, text is converted to lowercase and accents are removed. At query time, the same language-specific normalization is performed on the query text. For example:

query: "beyoncé"
query: "beyonce"

Several parameters control how a textual constraint is matched. Setting the prefixed parameter to true triggers a prefix match on name and aliases only (and a regular match on other textual data). For example:

query: "bob dy" prefixed: true

Setting stemmed to true triggers a stemmed match on name and aliases only (and a regular match on other textual data). Stemmed matches may be used to paste over language-specific suffix differences introduced by plurals or other grammatical forms. For example:

query: "potatos" stemmed: true

Surrounding the query text with double quotation marks ("") triggers a phrase match. The text tokens in the query must appear next to each other in the matching entity's textual data. For example:

query: "\"to be or not to be\""

Use the name, alias, and type parameters to match against people and person entities whose name contains the word you want to match. For example:

filter: "(all name:gore alias:gore type:/people/person)"

Similarly, the following example matches /people/person entities with a matching alias only and not their name:

filter: "(all (not name:gore) alias:gore type:/people/person)"

In addition to specifying what text fields should be matched, it is also possible to specify how the match should occur by inserting one of the following modifiers between the operand and the text field:

• {word}: require that the words in the string match words in the corresponding text field in the document. (default)
• {phrase}: require that the words occur next to each other in the same order in the corresponding text field in the document.
• {full}: like {phrase} but also require that the phrase completely match the text field, not just within the text field. In other words, a full match.

For example, to find the musical single called Home by Marc Broussard, use a filter like the following:

filter: "(all type:/music/single name{full}:home /music/track/artist:"Marc Broussard")"

Language constraints

As described with textual constraints, the lang parameter is used to specify what language normalization rules to use to transform text into query tokens. The language of the query also conditions result ranking as freebase-search gets a language-specific relevance signal from the corresponding language Wikipedia.

Currently, nine languages are supported: English (en), Spanish (es), French (fr), German (de), Italian (it), Portuguese (pt), Chinese (zh), Japanese (ja) and Korean (ko). English has by far the most coverage and is the default language.

Searching with multiple languages at the same time

The lang parameter accepts a comma-separated list of language codes that cause the search to be done in all the languages specified and the results to be ranked in the first language listed and displayed in the first language of the list that has a name for the entity.

For example:

The following searches for the German word "Sonnenblume" in German and French. It ranks and displays the results in French:

query: "Sonnenblume" lang: "fr,de"

The following searches in English for movies whose language is Korean and displays their Korean name. The English part of the query is the word "korean" in the expressed_by constraint:

filter: "(all expressed_by:korean type:/film/film)" lang: "ko,en"

Schema constraints

Schema constraints are specified with the type and the domain parameters. type corresponds to the /type/object/type property values of an entity.

For example, the following restricts a search to people only:

query: "gore" type: "/people/person"

domain corresponds to the /type/type/domain values of all /type/object/type values of an entity.

For example, the following restricts a search to entities in French in the /film domain only:

query: "babar" domain: "/film" lang: "fr"

You can also use individual Freebase properties to filter a query. For example, the following restricts a search to people who are from Canada:

 query "john" filter: "(all type:/people/person /people/person/nationality:"Canada")"

Metaschema constraints

Metaschema constraints filter entities by semantic predicates. These predicates are higher level concepts built from collections of Freebase properties describing similar semantic relationships.

Metaschema constraints are specified using the filter parameter operands combined with an entity name or MID constraint.

Supported Metaschema filter operands

The following Metaschema filter operands are supported by Freebase Search. Try out each example by clicking on the link in the table, or by using the Freebase Search Example App.

filter: "(all abstraction:fettuccine)"

filter: "(all abstraction_of:"Western Bulwark")"

filter: "(all adaptation_of:"La Traviata")"

filter: "(all type:awards administered_by:cannes)"

filter: "(all administers:synapse)"

filter: "(all appears_in:"magic flute")"

filter: "(all appears_in:"Die Zauberflöte")" lang: "de"

filter: "(all broader_than:"Airbus A319")"

filter: "(all category:female origin:france notable:actor)"

filter: "(all category:female origin:france practitioner_of:actor)"

filter: "(all category:volcano (any part_of:california part_of:france))"

filter: "(all category:pasta)"

filter: "(all type:airline center:"San Francisco")"

filter: "(all type:airline center:"San Francisco" center:atlanta)"

filter: "(all type:/book/newspaper center:/m/0d6lp)"

filter: "(all center_for:"san francisco 49ers")"

filter: "(all type:/film/film contributor:wenders certification:r)"

filter: "(all character:papageno)"

filter: "(all child:"bill clinton")"

filter: "(all contributed_to:"Blade Runner")"

filter: "(all type:/film/film contributor:"Steven Spielberg")"

filter: "(all type:/film/film contributor:/m/06pj8)"

filter: "(all type:/film/film contributor:"Harrison Ford")"

filter: "(all created:"for whom the bell tolls")"

filter: "(all notable:software created_by:google)"

filter: "(all discovered:radium)"

filter: "(all discovered_by:curie)"

filter: "(all type:show distributed_by:npr)"

filter: "(all exhibited:"down by law")"

filter: "(all type:"nominated work" exhibited_at:"2010 Cannes Film festival")"

filter: "(all type:book expressed_by:esperanto)"

filter: "(all type:/fictional_universe/fictional_character fiction_link:"mickey mouse")"

filter: "(all category:cathedral genre:gothic)"

filter: "(all category:cathedral genre:gothic created_by:viollet)"

filter: "(all identifies:"Southwest Airlines")"

filter: "(all type:company leader:kapor)"

filter: "(all title:mayor leader_of:paris)"

filter: "(all type:painting made_of:wax)"

filter: "(all type:politician means_of_demise:"capital punishment")"

filter: "(all type:monarch member_of:africa)"

filter: "(all type:politician member_of:democratic notable:actor)"

filter: "(all type:engine narrower_than:"v8 engine")"

filter: "(all type:language occurs_in:romania)"

filter: "(all title:governor member_of:republican origin:austria)"

filter: "(all type:make owner:ford)"

filter: "(all owns:mavericks)"

filter: "(all parent:"al gore")"

filter: "(all type:/computer/programming_language parent:lisp)"

filter: "(all type:lake part_of:sweden)"

filter: "(all type:competition part_of:"2008 summer olympics")"

filter: "(all participant:bowie type:concert)" 

filter: "(all notable:skier member_of:austria participated_in:olympics)"'

filter: "(all notable:politician peer_of:gore)"

filter: "(all permits_use_of:diesel)"

filter: "(all notable:actor portrayed:"john lennon")"

filter: "(all portrayed_by:"Harrison Ford")"

filter: "(all category:female category:"african american" practitioner_of:lawyer)"

filter: "(all type:/film/film preceeding:"The Lord of the Rings, the two Towers")"

filter: "(all type:computers produced_by:apple)"

filter: "(all publication:/m/0clw238)"

filter: "(all publication_of:"La Traviata")"

filter: "(all type:broadcaster service_area:california)"

filter: "(all type:glacier status:retreating part_of:switzerland)"

filter: "(all subclass_of:swimwear)"

filter: "(all type:film subject:holocaust)"

filter: "(all type:book subject:mathematics)"

filter: "(all type:/film/film subsequent:"The Lord of the Rings, the two Towers")"

filter: "(all succeeded_by:"ford b3 platform")"

filter: "(all succeeds:stuart)"

filter: "(all superclass_of:"coronary heart disease")"

filter: "(all title:engineer member_of:google)"

filter: "(all type:battles tookplace_at:marengo)"

filter: "(all type:"file format" use_permitted_by:iphone)"

Scoring and ranking

Freebase entities have an inherent relevance score (ranking) computed during indexing that is function of its inbound and outbound link counts in Freebase and Wikipedia. Some popular Freebase entities also have a popularity score computed by Google. By default, both scores are combined together during queries.

When a textual constraint is present, a textual match score is computed from the number of hits returned by the search index and is combined with the relevance score.

FreebaseSearch results are always sorted by the final score, highest score first.

The scoring parameter makes it possible to control what relevance score components are used to compute the final score:

freebase: Use only the Freebase relevance score.

query: "beyoncé" scoring: freebase

entity: Use both relevance scores, which replaces any missing Google scores to 1.0. This is the default.

query: "beyoncé" scoring: entity

schema: Use when looking for schema entities like types, properties or domains. The link counts of schema entities is computed differently.

query: "performance" scoring: schema

Other constraints

Entities can be filtered by index tag using the with or without parameters. Entities are tagged during indexing, each tag corresponding to one or several Freebase queries that would be too expensive to run during search:

commons is a tag that can be used to restrict a schema search to returning only Freebase Commons schema. For example, Freebase Commons types matching the word "color"

query: "color" type: "/type/type" with: "commons"

gg is a tag that can be used to restrict a search to entities for which there is or isn't a Google popularity score.

query: "1923" type: "/people/person" with: "gg"
query: "1923" type: "/people/person" without: "gg"

The without parameter is equivalent to the a negated with in a filter expression.

query: "color" limit: 5 type: "/type/type" without: "commons"
query: "color" limit: 5 type: "/type/type" filter: "(not with:commons)"