- Textual constraints
- Language constraints
- Schema constraints
- Metaschema constraints
- Scoring and ranking
- 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.
| Operand Name | Example(s) |
|---|---|
abstraction |
"fettuccine dishes" (Try it.)
filter: "(all abstraction:fettuccine)" |
abstraction_of |
"class of the Western Bulwark locomotive" (Try it.)
filter: "(all abstraction_of:"Western Bulwark")" |
adaptation |
"Works La Traviata is an adaptation of" (Try it.)
filter: "(all adaptation_of:"La Traviata")" |
administered_by |
"Cannes awards" (Try it.)
filter: "(all type:awards administered_by:cannes)" |
administers |
"Who runs the Synapse newspaper?" (Try it.)
filter: "(all administers:synapse)" |
appears_in |
"characters in the Magic Flute" (Try it.)
filter: "(all appears_in:"magic flute")" filter: "(all appears_in:"Die Zauberflöte")" lang: "de" |
broader_than |
"line of aircraft that the Airbus 319 belongs to" (Try it.)
filter: "(all broader_than:"Airbus A319")" |
category |
"french actresses" (Try it.)
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))" "pasta dishes" (Try it.) filter: "(all category:pasta)" |
center |
"airlines with a hub in San Francisco" (Try it.)
filter: "(all type:airline center:"San Francisco")" filter: "(all type:airline center:"San Francisco" center:atlanta)" filter: "(all type:/book/newspaper center:/m/0d6lp)" |
center_for |
"sports facilities for the San Francisco 49ers" (Try it.)
filter: "(all center_for:"san francisco 49ers")" |
certification |
"R-rated movies by Wim Wenders" (Try it.)
filter: "(all type:/film/film contributor:wenders certification:r)" |
character |
"works which have Papageno as character" (Try it.)
filter: "(all character:papageno)" |
child |
"parents of Bill Clinton" (Try it.)
filter: "(all child:"bill clinton")" |
contributed_to |
"Who contributed to Blade Runner?" (Try it.)
filter: "(all contributed_to:"Blade Runner")" |
contributor |
"movies by Steven Spielberg" (Try it.)
filter: "(all type:/film/film contributor:"Steven Spielberg")" filter: "(all type:/film/film contributor:/m/06pj8)" filter: "(all type:/film/film contributor:"Harrison Ford")" |
created |
"who created 'for whom the bell tolls'" (Try it.)
filter: "(all created:"for whom the bell tolls")" |
created_by |
"software by Google" (Try it.)
filter: "(all notable:software created_by:google)" |
discovered |
"discoverers of radium" (Try it.)
filter: "(all discovered:radium)" |
discovered_by |
"discoveries by Curie" (Try it.)
filter: "(all discovered_by:curie)" |
distributed_by |
"NPR shows" (Try it.)
filter: "(all type:show distributed_by:npr)" |
exhibited |
"where was 'down by law' presented ?" (Try it.)
filter: "(all exhibited:"down by law")" |
exhibited_at |
"nominated works shown at the 2010 Cannes Film Festival" (Try it.)
filter: "(all type:"nominated work" exhibited_at:"2010 Cannes Film festival")" |
expressed_by |
"books in esperanto" (Try it.)
filter: "(all type:book expressed_by:esperanto)" |
fictional_link |
"fictional characters related to Mickey Mouse" (Try it.)
filter: "(all type:/fictional_universe/fictional_character fiction_link:"mickey mouse")" |
genre |
"gothic cathedrals" (Try it.)
filter: "(all category:cathedral genre:gothic)" filter: "(all category:cathedral genre:gothic created_by:viollet)" |
identifies |
"What identifies Southwest Airlines?" (Try it.)
filter: "(all identifies:"Southwest Airlines")" |
leader |
"Mitch Kapor companies" (Try it.)
filter: "(all type:company leader:kapor)" |
leader_of |
"Paris mayors" (Try it.)
filter: "(all title:mayor leader_of:paris)" |
made_of |
"wax paintings" (Try it.)
filter: "(all type:painting made_of:wax)" |
means_of_demise |
"executed politicians" (Try it.)
filter: "(all type:politician means_of_demise:"capital punishment")" |
member_of |
"african monarchs" (Try it.)
filter: "(all type:monarch member_of:africa)" filter: "(all type:politician member_of:democratic notable:actor)" |
narrower_than |
"examples of v8 engines" (Try it.)
filter: "(all type:engine narrower_than:"v8 engine")" |
occurs_in |
"languages spoken in Romania" (Try it.)
filter: "(all type:language occurs_in:romania)" |
origin |
"Republican governors from Austria" (Try it.)
filter: "(all title:governor member_of:republican origin:austria)" |
owner |
"makes owned by Ford" (Try it.)
filter: "(all type:make owner:ford)" |
owns |
"Who owns the Mavericks?" (Try it.)
filter: "(all owns:mavericks)" |
parent |
"Al Gore's children" (Try it.)
filter: "(all parent:"al gore")" filter: "(all type:/computer/programming_language parent:lisp)" |
part_of |
"swedish lakes" (Try it.)
filter: "(all type:lake part_of:sweden)" filter: "(all type:competition part_of:"2008 summer olympics")" |
participant |
"Bowie concerts" (Try it.)
filter: "(all participant:bowie type:concert)" |
participated_in |
"Notable austrian skiers who participated in Olympics" (Try it.)
filter: "(all notable:skier member_of:austria participated_in:olympics)"' |
peer_of |
"politicians peers of Al Gore" (Try it.)
filter: "(all notable:politician peer_of:gore)" |
permits_use_of |
"Diesel engines" (Try it.)
filter: "(all permits_use_of:diesel)" |
portrayed |
"actors who portrayed John Lennon" (Try it.)
filter: "(all notable:actor portrayed:"john lennon")" |
portrayed_by |
"characters portrayed by Harrison Ford" (Try it.)
filter: "(all portrayed_by:"Harrison Ford")" |
practitioner_of |
"female african american lawyers" (Try it.)
filter: "(all category:female category:"african american" practitioner_of:lawyer)" |
preceeding |
"sequels to The Lord of the Rings, the two Towers" (Try it.)
filter: "(all type:/film/film preceeding:"The Lord of the Rings, the two Towers")" |
produced_by |
"Apple computers" (Try it.)
filter: "(all type:computers produced_by:apple)" |
publication |
"which book has /m/0clw238 as first edition ?" (Try it.)
filter: "(all publication:/m/0clw238)" |
publication_of |
"releases of La Traviata" (Try it.)
filter: "(all publication_of:"La Traviata")" |
service_area |
"California broadcasters" (Try it.)
filter: "(all type:broadcaster service_area:california)" |
status |
"retreating swiss glaciers" (Try it.)
filter: "(all type:glacier status:retreating part_of:switzerland)" |
subclass_of |
"kinds of swimwear" (Try it.)
filter: "(all subclass_of:swimwear)" |
subject |
"movies about the Holocaust" (Try it.)
filter: "(all type:film subject:holocaust)" filter: "(all type:book subject:mathematics)" |
subsequent |
"prequels to The Lord of the Rings, the two Towers" (Try it.)
filter: "(all type:/film/film subsequent:"The Lord of the Rings, the two Towers")" |
succeeded_by |
"Which automotive platform was succeeded by the Ford B3 platform ?" (Try it.)
filter: "(all succeeded_by:"ford b3 platform")" |
succeeds |
"Who succeeded the House of Stuart ?" (Try it.)
filter: "(all succeeds:stuart)" |
superclass_of |
"Classes coronary heart disease belongs to" (Try it.)
filter: "(all superclass_of:"coronary heart disease")" |
title |
"Google engineers" (Try it.)
filter: "(all title:engineer member_of:google)" |
tookplace_at |
"battles that took place at Marengo" (Try it.)
filter: "(all type:battles tookplace_at:marengo)" |
use_permitted_by |
"File formats supported on an iPhone" (Try it.)
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)"