Enumeration

From Freebase

Jump to: navigation, search

An enumeration is a namespace in which MQL creates human-readable unique indentifiers for instances. This identifier can be used as a foreign key to simplify reconciliation between Freebase and other datasets, provides a way to access Freebase topics without needing to reference the Globally Unique Identifier (GUID), and enforces uniqueness among Freebase topics. An example of enumeration would be the NCBI Taxon ID, where the number 9233 refers to the Emperor Penguin.

Enumerations are typically most useful when there is an external authority (such as an international standard) that defines the names or uses ids/keys to maintain distinct records to reduce ambiguity.

An object of /type/enumeration that has a specified enumeration namespace. For each instance of the enumerated type, MQL creates a unique identifier, or key, in the enumerated namespace. Enumerated types allow you to refer to instances of the type easily by key value. For example, for the enumerated type /people/gender, whose enumeration namespace is /topic/en, the instances male and female may easily be referred to by the keys /topic/en/male and /topic/en/female.

See also:

Enumerations 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!

An enumeration is MQL's mechanism for connecting a type with the namespace that defines names for objects of that type. An enumeration takes the form of a property whose expected type is /type/enumeration. If a type has a property like this, then setting the value of that property on an object defines a key in the associated namespace. The property value is the name of the key, and the key refers to the object on which the property was set. Similarly, if you create a name in the namespace that refers to an object, then that object automatically gets a value for the property.

The type /type/lang is associated with the namespace /lang through the enumerated property iso639. (ISO639 is the name of an international standard defining short codes such as "en" and "fr" for language names.) This means that for any object of /type/lang, the value of the iso639 property is also a used to define a fully-qualified name in the the /lang namespace. The following query (and partial set of results) demonstrates:

QueryResult
[{
  "type":"/type/lang",
  "name":null,
  "id":null,
  "iso639":null
}]
[{
  "type" : "/type/lang",
  "name":"English",
  "id" : "/lang/en",
  "iso639" : "en"
},{
  "type" : "/type/lang",
  "name":"German",
  "id" : "/lang/de",
  "iso639" : "de"
},{
  "type" : "/type/lang",
  "name":"Spanish",
  "id" : "/lang/es",
  "iso639" : "es"
},{
  "type" : "/type/lang",
  "name":"French",
  "id" : "/lang/fr",
  "iso639" : "fr"
}]

/type/lang defines the iso639 property so that its value becomes part of the fully-qualified name of the object. In a sense, then, this iso639 property is the "unqualified name" or "local id" of every /type/lang object. So language objects have a human-readable name, a fully-qualified, hierarchical id, and this local name, the values of which are defined (or "enumerated") by international standard ISO639.

Let's investigate the iso639 property itself:

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

We see from this query that the property has expected type /type/enumeration, and that it has a property named enumeration that refers to associated namespace. Since we already know that the /lang namespace is unique (no language can have more than one name in the namespace), it follows that this iso639 property must also be defined as a unique property: it cannot make sense to have more than one value for the property.

The userid property of /type/user is an important enumeration that links /type/user objects with the /user namespace. Another notable example involves taxonomy. The type /biology/organism_classification has two enumerated properties: the itis_tsn property links to the /biology/itis namespace and the ncbi_taxon_id links to the /biology/ncbi namespace. For example, the Metaweb object representing the species Equus caballus (horses) has its itis_tsn property set to "180691" and its ncbi_taxon_id set to "9796" and can be referred to as: /biology/itis/180691 or /biology/ncbi/9796. For this type, neither the enumerated properties nor the namespaces they refer to are marked unique, which means that either the ITIS or NCBI classification scheme may allow multiple names for the same species.

NOTE: It should be clear from these examples that MQL enumerations are not really the same thing as the "Enumerated types" (a type that has a small, pre-defined set of allowed values) that are supported by some programming languages. The name "enumeration" refers to the fact that the namespace associated with the enumerated property enumerates instances of the type.

Recall that the names defined in namespaces are restricted to using letters, numbers, and underscores. Any other characters must be written as a dollar sign followed by the four hexadecimal digits of its Unicode codepoint. MQL does not impose this restriction on enumerated properties. Instead, it transparently escapes and un-escapes names as needed. That is, if you set the value of an enumerated property to a string that contains a punctuation character, that character will automatically be escaped in the namespace. Similarly, if a key contains escaped punctuation but you read it through an enumerated property, the escapes will be replaced by the characters they represent. This can't be demonstrated using the /lang, /user or /biology namespaces we've mentioned here, since none of them define names that include punctuation. But we'll see an example in MQL Manual/MQL write grammar when we define our enumerated properties for types of our own.

Personal tools