Id

From Freebase

Jump to: navigation, search

An identifier or ID in Freebase is a string used to identify any node in the graph. Many topics have a human readable ID in the '/en' namespace which is intended to be stable (e.g. /en/barack_obama). Topics may have additional identifiers as well. IDs are stored in Freebase using the MQL key escaping scheme.

Contents

IDs, keys, and namespaces

IDs are closely associated with keys. Every key exists in a namespace (directory) and the hierarchy of namespaces and associated keys forms a path which uniquely identifies a single graph node. A single node may have multiple IDs. Because our example was imported from Wikipedia, it also has the IDs /wikipedia/en_id/534366 and /wikipedia/en/Barack_Obama based on its Wikipedia article number and title.

WebIDs

Web IDs are world-wide strong identifiers that you and your software can use to precisely identify and distinguish concepts, even if they share the same names.

For example: "Jaguar" can be used to refer to several distinct concepts (the animal, the car company, the musical artist, etc.) but each of them have different Web IDs. Whereas keywords are ambiguous, Web IDs are precise.

MIDs

All nodes have a MID which can be used as an ID when prefixed with the synthetic namespace '/m' (e.g. /m/07jlw9). MIDs are assigned when a node is created and remain unchanged. When topics get merged MIDs point to the merge winner. This makes MIDs useful as an external handle to Freebase topics because they are stable in the face of merges.

GUIDs

All nodes have a GUID which can be used as an ID when prefixed with the synthetic namespace '/guid' (e.g. /guid/9202a8c04000641f800000000029c277). GUIDs are assigned when a node is created and remain unchanged.

Finding all IDs

You can see what IDs exist for a given topic by looking at the Freebase edit page or by using the Acre app at http://ids.freebaseapps.com/

You can also use this MQL query:

[{
 "id": "/en/barack_obama",
 "key": [{
   "*": []
 }]
}]

Searching for matching IDs

Acre app: http://key-search.freebaseapps.com/

IDs, keys, and MQL

This article contains content originally taken from the MQL Manual, which is no longer maintained. It may need cleanup to make sense as a standalone document. Please go ahead and help us do this!


Objects can be given fully-qualified names that can be used as unique identifiers. Query the id property of an object to obtain a unique identifier for it:

<tgroup cols="2"> <thead></thead> <tbody></tbody></tgroup>
QueryResult
{
  "type" : "/music/artist",
  "name" : "The Police", 
  "id" : null
}
{
  "type": "/music/artist", 
  "name": "The Police",
  "id": "/en/the_police"
}

This query includes the same name and type as the last query. But instead of specifying an empty array of albums, it specifies a null id. The null value is our query: this is the field we want Metaweb to fill in. The response looks just like the query, but the null has been replaced with a unique fully-qualified name for The Police.

In addition to querying the id property of an object, we can also use it to uniquely name the object we want. We could rewrite our musical albums query to use id instead of name, for example:

{
  "type": "/music/artist",
  "id": "/en/the_police",
  "album": []
}

Metaweb objects are not required to have a fully-qualified name, but every object is assigned a string of hexadecimal digits that serves as a globally unique identifier or guid. If you query the id property of an object that does not have a fully-qualified name, Metaweb creates a synthetic identifier by prefixing the object's guid with /guid/:

<tgroup cols="2"> <thead></thead> <tbody></tbody></tgroup>
QueryResult
{
  "type" : "/music/album",
  "artist": "The Police",
  "name" : "Synchronicity", 
  "id" : null
}
{
  "type": "/music/album", 
  "artist": "The Police",
  "name": "Synchronicity",
  "id": "/guid/9202a8c04000641f8000000002f9e349"
}

You can use guid-based identifiers as the value of the id property to uniquely identify an object.

Ids

The most important thing about the id property is that if you specify its value, you are uniquely identifying a single object in the database. A query that specifies id need not have square brackets around it: it can never return more than one value. It is also a good rule of thumb (though not always strictly necessary) to put square brackets around any query that does not specify the id property.

It is always safe to query the id of an object with "id":null. This query will always return exactly one value (even if the object has more than one fully-qualified name). If the object does not have any fully-qualified names, Metaweb returns a pseudo-id using the object's guid and the /guid namespace. For example:

QueryResult
{
  "type" : "/music/album",
  "artist": "The Police",
  "name" : "Synchronicity", 
  "id" : null
}
{
  "type" : "/music/album",
  "artist" : "The Police",
  "name" : "Synchronicity",
  "id" : "/guid/9202a8c04000641f8000000002f9e349"
}

There is a one-to-one mapping between objects and guids: every object has one guid, and every valid guid must refer to a different object. Ids are less strict: no two objects can have the same id, but an object can have zero, one, or more fully-qualified names. We can refer to the Metaweb object that represents the band The Police with any of the following:

"id":"/guid/9202a8c04000641f800000000006df1b"
"id":"/en/the_police"
"id":"/wikipedia/en_id/57321"
"id":"/wikipedia/en/Police_band"

There are some restrictions on what you can do with the id property: it cannot be used as a sort key, and it cannot be used with operators such as ~= and &lt; (We'll learn about sorting and operators later in this chapter.)

Also, you cannot query all the fully-qualified names of an object with "id":[]:

QueryResult
{
  "type" : "/music/artist",
  "name" : "The Police", 
  "id" : []
}
{
  "type": "/music/artist", 
  "name": "The Police",
  "id": ["/en/the_police"]
}

"id":[] returns a single valid id for the object, just as "id":null does, but it wraps it in square brackets. To find multiple fully-qualified names of an object, you must query its keys, which are the topic of the next section.

Keys and Namespaces

To ask for multiple fully-qualified names for an object, query its key property. The following query asks for all properties of all keys of The Police.

<tgroup cols="2"> <thead></thead> <tbody></tbody></tgroup>
QueryResult
{
  "id":"/en/the_police",
  "key":[{}]
}
{
  "id" : "/en/the_police",
  "key" : [{
    "type" : "/type/key",
    "namespace" : "/en",
    "value" : "the_police"
  },{
    "type" : "/type/key",
    "namespace" : "/wikipedia/en_id",
    "value" : "57321"
  },{
    "type" : "/type/key",
    "namespace" : "/wikipedia/en",
    "value" : "Police_band"
  },{
    "type" : "/type/key",
    "namespace" : "/wikipedia/en",
    "value" : "The_Police_$0028band$0029"
  }]
}

The results of this query have been truncated, but there are two things worth noting about the representative keys shown here. First, fully-qualified names can contain numbers and underscores, but they cannot contain punctuation. If a local name contains punctuation such as parentheses, these must be escaped using Unicode codepoints. For example, $0028 in a fully-qualified name represents a left parenthesis and $0029 represents a right parenthesis. (See <xref linkend="typekey"/> for the full list of legal characters in fully-qualified names.)

Second, note that these keys do not include a key in the /guid namespace. /guid ids are synthesized by Metaweb when no fully-qualified name exists: they do not represent a real key.

The query above returns keys representing multiple fully-qualified names for The Police. Those results are not necessarily a complete list, however. The keys refer to namespaces, and the namespaces themselves can have more than one fully-qualified name. Consider the /en namespace:

<tgroup cols="2"> <thead></thead> <tbody></tbody></tgroup>
QueryResult
{
  "id":"/en",
  "key":[{}]
}
{
  "id" : "/en",
  "key" : [{
    "type" : "/type/key",
    "namespace" : "/topic",
    "value" : "en"
  },{
    "type" : "/type/key",
    "namespace" : "/",
    "value" : "en"
  }]
}

This query tells us that our namespace object has the name "en" in the root namespace /, but that it also has the name "en" in the namespace /topic. This means that the fully-qualified name /en/the_police can also be written as /topic/en/the_police.

The keys of an object all refer to namespace objects in which those keys are defined. Since Metaweb links are bi-directional, it must also be possible to query a namespace to find out what names are defined in it. Here's a query on the /topic namespace. It queries the key property we've already seen to ask for the fully-qualified names of this object. But it also queries the keys property to find out what keys are defined in /topic. (The key property is defined by /type/object. The keys property is defined by /type/namespace, and is plural to avoid naming conflicts with key.):


<tgroup cols="2"> <thead></thead> <tbody></tbody></tgroup>
QueryResult
{
  "type":"/type/namespace",
  "id":"/topic",
  "key":[{}],
  "keys":[{}]
}
{
  "type" : "/type/namespace",
  "id" : "/topic",
  "key" : [{
    "namespace" : "/",
    "type" : "/type/key",
    "value" : "topic"
    }],
  "keys" : [{
    "namespace" : "/en",
    "type" : "/type/key",
    "value" : "en"
  }]
}

The results tell us that the object /topic has only the one fully-qualified name we already know: the local name "topic" in the namespace /. They also tell us that there is only a single key defined in the /topic namespace. This key has the local name "en", which means that it defines the fully-qualified name /topic/en.

Both the key and keys properties return values of /type/key. The namespace properties of these keys have different meanings, however. When you query the key property of an object, the namespace property of each returned key refers to the namespace object in which the key is defined. When you query the keys property of a namespace, however, the namespace property of each returned key specifies the object whose name is defined by that key. So the query above tells us that the /topic namespace defines a key named "en" that refers to an object with id /en. That is /topic/en is another fully-qualified name for /en.

Finally, it is worth noting that any Metaweb object can serve as a namespace, even if it does not have a type property of /type/namespace. Types (such as /music/artist) have ids that use the domain (/music) as a namespace, and properties (such as /music/artist/album have ids that use the type as a namespace. At the time of this writing, <footnote><para>September, 2008</footnote> Metaweb domains and types very often do not have /type/namespace among their types. Despite these examples, it is not recommended practice to use an object as a namespace without typing it as a namespace.

     </para>
   


Namespaces and Uniqueness

A namespace can define any number of keys, but the value property of each key must be different. Otherwise, the same fully-qualified name would be defined twice, and could refer to more than one object. On the other hand, the reverse is not necessarily true: normal namespaces can define multiple keys that refer to the same object. For example, we've already seen that the /wikipedia/en namespace defines "Police_band" and "The_Police_$0028band$0029" as names for the same object.

Not all namespaces allow multiple names for the same object, however. A namespace may be declared to be "unique", and unique namespaces enforce a one-to-one mapping between names and objects: each name can refer to only one object and each object can have only one name. The /user and /lang namespaces are unique, which means that each user and language can have only a single fully-qualified name (assuming that /user and /lang don't have any other ids themselves). Most other namespaces, such as /en are not unique. Unique namespaces have the unique property of /type/namespace set to true. Namespaces that are not unique typically have null for this property.


<tgroup cols="2"> <thead></thead> <tbody></tbody></tgroup>
QueryResult
{
  "id":"/lang",
  "type":"/type/namespace",
  "unique":null
}
{
  "id" : "/lang",
  "type" : "/type/namespace",
  "unique" : true
}



See also

Personal tools