When viewed at the lowest level, the Metaweb graph is a set of nodes and a set of links or relationships between those nodes. Each node has a unique identifier (so it can be named and referred to) and a record of when and by whom it was created. Other than the id, timestamp and creator, however, the nodes in the graph hold no information themselves. All the interesting data in the database is stored in the form of relationships between nodes (or between nodes and primitive values).

Graphs can be represented visually using circles to represent nodes and arrows between the circles to represent relationships. In this section, however, we will model the relationships in the Metaweb object store as a tuples of four pieces of data ^[2] and we will represent sets of these relationships in tabular form, where each row of a table specifies one tuple.

The table below, for example, represents information about The Police, their album Zenyatta Mondatta, and the song Driven to Tears on that album. The From column identifies the node that is the subject of the relationship. This node could also be called the "source" node or the "left" node. The Property column specifies the kind of relationship being described. (Notice that this complicates the visual representation of a Metaweb graph: each arrow in the diagram must be tagged with a property to specify what kind of relationship it represents.) The To and Value columns specify the object of the relationship. To (which could also be called "target", "destination", or "right" specifies another node, and Value specifies a primitive value such as a string of text, a number or a date. One or both of these columns may have a value, depending on the kind of relationship (the Property column) being described.

The first three rows of this table describe a /type/object/name relationship, which defines a human-readable name for a node. Thus, the node we've identified as /en/the_police has the name "The Police", and the node /guid/1234 has the name "Driven to Tears". Notice that these rows have a value in the To column as well as the Value column, and that the To column refers to the node identified as /lang/en. That node represents the English language. Human readable text in Metaweb is always tagged with the language in which it is written. Thus any relationship, such as /type/object/name, that expects a human-readable text value will refer to a language node in the To column and will have a string of text in the Value column.

The fourth row in the table specifies that /en/zenyatta_mondatta has the relationship /music/album/artist with /en/the_police. In English, we might say: "Zenyatta Mondatta is by The Police". The fifth row is similar. It specifies a /music/track/album relationship between two nodes. It says: "Driven to Tears appears on Zenyatta Mondatta". Finally, the sixth row specifies the /music/track/length of Driven to Tears. Note that this relationship is not a link between two nodes, but merely specifies a number in the Value column.

The Property column of our relationship tables have specified relationships with names like /type/object/name and /music/track/album, and you may have wondered about the fact that these property identifiers look so much like node identifiers that appear in the From and To columns. One of the key features of Metaweb is that it does not pre-define the kinds of relationships that can exist between nodes. New properties, representing new kinds of relationships, can be defined at any time and by any user. What this means, of course, is that properties are themselves nodes in the Metaweb graph.

Since properties are nodes, they can appear in the From column of a table of tuples, and can have relationships themselves. For example:

The first row in this table is interestingly self-referential. The /type/object/name property defines its own name as "Name". The second and third rows define names for the /music/album/artist and /music/track/album properties, and it is worth noting that the human-readable names of Metaweb nodes are not always the same as the last component of the node identifier.

In an example above, we used the identifier /en/the_police to refer to a node that has the /type/object/name "The Police". This section explains the important differences between names and identifiers.

The /type/object/name property defines a human-readable name for a node. The value of the property includes both the text and the language of the name. As we saw above:

Nodes can have more than one name, but Metaweb enforces an important constraint: a node can have only one name in any given language. (Use /common/topic/alias to define any number of nicknames, in any language, for a node.) As an example, the following table shows hypothetical English, French and Spanish names (and aliases) for the /lang/en node:

Names are not unique and not expected to be: it is common for multiple nodes to have the same name. The nodes with ids /lang/en, /en/english_people, and /authority/gnis/57724 represent a language, a nationality, and a town in Arkansas and all have the name "English".

When you ask Metaweb for the name of a node without specifying a language, it returns only the node's name in your preferred language, fostering the convenient illusion that the node has only a single name. Human-readable names exist for the convenience of the human users of Metaweb, and although they are treated specially by the Metaweb architecture, they are not really fundamental to that architecture.

Identifiers, on the other hand, are fundamental. Identifiers consist of three parts: the node that is identified, a namespace and a key within the namespace. The identifier /en/the_police identifies a node in the graph that represents the band The Police. It has namespace /en and key "the_police". The identifier /type/object/name identifies a property node with namespace /type/object and key "name". /type/object is itself an identifier, with namespace /type and key "object". We can also turn this around and say that the namespace /lang and key "en" combine to define the identifier /lang/en. We'll return to the notion of an identifier as a node, a namespace, and a key in Section 2.5.9.

A key can be considered a "local name" within a namespace, and the key plus namespace pair can be called a "fully-qualified name" to distinguish it from a "human-readable name". Usually, however, the pair is simply called an identifier or id. As you have seen, Metaweb identifiers are typically written in "flat form" as strings that use a slash character to separate the namespace from key. This means that identifiers look something like Unix filenames or URLs. Identifiers are intended for use by developers and are often used in code, which is why they appear in code font in this manual.

The important thing about identifiers is that they are unique. Metaweb never allows a namespace to contain duplicate keys, which means that two nodes will never have the same identifier. A node can be associated with more than one namespace/key pair, but any given namespace and key can only be used once, and can only refer to a single node. Note that identifiers are not immutable: nodes can be given new identifiers, and identifiers can be altered so that they refer to new nodes.

Identifiers like /en/the_police are not human-readable names, but are comprehensible to technically-savvy English-speakers, like the readers of this manual. Many nodes in a Metaweb graph (and most nodes on freebase.com) have identifiers of this kind. Those that don't can be referred to using identifiers in the namespace /guid. The key that follows /guid is a string of hexadecimal digits that serves as a globally-unique identifier (or "guid") for a node. The song "Driven to Tears" from the album Zenyatta Mondatta, for example has the identifier /guid/9202a8c04000641f800000000129a87a (we called it /guid/1234 for brevity earlier in the chapter).

Every node in a Metaweb graph has a numeric guid. The guid uniquely identifies the node and is immutable – the guid of a node can never change. The guid is the fundamental identity of a Metaweb node, and at the implementation level, the tuples that define the Metaweb graph refer to nodes (in the From, Property, and To columns) by their guids, not by the identifiers that we've shown in our tables.

Since the guid is the fundamental identity of a node, the identifier of a node is not fundamental. In fact, identifiers are defined by the /type/object/key property, much as names are defined by the /type/object/name property. Here, for example, are tuples that define the identifiers /en/the_police and /en/zenyatta_mondatta.

The /type/object/key property expects values in both the To and Value columns. The To column is a reference to the namespace of the identifier being defined, and the Value column holds the key within the namespace. Namespaces are themselves nodes, and they have identifiers. The third row of the table above shows that the identifier of the /en namespace is defined by the "en" key within the special root namespace /. For clarity, these example tuples use ids in each of the columns, which means that they define and use an identifier at the same time. A more accurate representation of the underlying graph would use guids in place of these ids.

A proper understanding of names, ids and namespaces is critical to understand Metaweb, and we'll review and explore them in more depth in Section 3.3 and Section 5.11.

Until now we've been describing the Metaweb database as a graph of nodes and relationships, and have been carefully avoiding the word "object". But that word has appeared many times in property ids like /type/object/key and /freebase/documented_object/tip. While it is important to understand that at a low-level Metaweb databases consist of tuples that define relationships between nodes, it is usually helpful to view those nodes and relationships at a higher level through an object-oriented filter.

According to this object-oriented view, the nodes in the graph define objects, and the relationships in the graph define properties of those objects. Instead of thinking about the relationship between The Police, Zenyatta Mondatta and Driven to Tears in terms of tuples, we might think of them using pseudo-code ^[4] like this:

{
  id: "/en/the_police",
  name: "The Police",
  /music/artist/album: {
    id: "/en/zenyatta_mondatta",
    name: "Zenyatta Mondatta",
    /music/album/track: {
      name: "Driven to Tears",
      /music/track/length: 200.266
    }
    /music/album/track: {
      name: "Canary in a Coalmine",
      /music/track/length: 146.506
    }
  }
}

In this view of the data, we see an object with id /en/the_police and name "The Police". (We're using properties id and name as shorthand for the "universal" /type/object/id and /type/object/name properties that are shared by all objects. We'll have more to say about these universal properties below.) That object has an album named "Zenyatta Mondatta", and that album has two tracks (others are omitted here for simplicity) named "Driven to Tears" and "Canary in a Coalmine". Each of those track objects has a length property that specifies its length in seconds. Note that this particular view of the data relies on the properties /music/artist/album and /music/album/track. These are the reverse of the /music/album/artist and /music/track/album properties that we saw in the nodes-and-relationships view of the data.

In order to complete the object-oriented view of Metaweb nodes, we have to introduce the notion of types. A Metaweb type is a collection of related properties, and a Metaweb object can be an instance of one or more types. /en/the_police is an instance of the type /music/artist, /en/zenyatta_mondatta is an instance of /music/album, and the object that represents the track Driven to Tears is an instance of /music/track. Like properties, types are represented as nodes in the graph. Every property node is an instance of /type/property, and every type node is an instance of /type/type (which means that /type/type is an instance of itself!) Property objects use the type of which they are a part as the namespace in which their id is defined. So the properties of /music/track, such as /music/track/album and /music/track/length, have ids that begin with /music/track.

Types and properties are related via the (unique) /type/property/schema property, which defines the relationship between a property and the type of which it is a part. The reverse property /type/type/properties represents the (non-unique) relationship between a type and all of its properties.

There are two other, more important, properties that involve types. The first is /type/object/type. Like /type/object/name and /type/object/key, this is a universal property that is used on practically all object in the database. It defines the types (it is non-unique) that an object belongs to. If we ask the Metaweb engine at freebase.com about the types of the /en/the_police object, for example, we find that in addition to /music/artist, that object is also an instance of /common/topic, /music/producer, and /music/musical_group.

The /type/object/type property is important for a couple of reasons. First, the type of an object tells us what properties it is likely to have. For example, if we know that an object is a /music/artist, we know it makes sense to ask about the /music/artist/album property of the object. Second, the type of an object is a useful disambiguator. If we ask Metaweb for objects named "English", we will likely find many. We can substantially narrow our search by asking for for objects named "English" that are also instances of /type/lang.

In addition to /type/object/type, there is one other very important type-related property. The (unique) /type/property/expected_type property of any property specifies the type of the value of that property. The expected type of the /music/artist/album property, for example, is /music/album, and the expected type of /music/album/track is /music/track.

The addition of types to our object-oriented view of the Metaweb graph allows us to simplify our pseudo-code representation of it. Compare this object representation with the one at the beginning of this section:

{
  id: "/en/the_police",
  type: "/music/artist",
  name: "The Police",
  album: {
    id: "/en/zenyatta_mondatta",
    name: "Zenyatta Mondatta",
    track: {
      name: "Driven to Tears",
      length: 200.266
    }
    track: {
      name: "Canary in a Coalmine",
      length: 146.506
    }
  }
}

We've added a type property to the outermost object, specifying that it is a /music/artist. This allows us to use the simple property name album instead of /music/artist/album. Furthermore, since we know that expected type of /music/artist/album is /music/album, we're now just using the property name track instead of /music/album/track. For the same reason, we've shortened /music/track/length to length.

Both the /type/object/type and /type/property/expected_type properties are a very useful part of the object-oriented view of Metaweb, but they are not fundamental to the nodes-and-relationships view. A node in the graph can have a relationship described by a property p even if that node does not have a /type/object/type relationship with the type that defines p. That is, an object can use a property without "declaring" itself to be a member of the type that defines the property. Properties like /type/object/name, for example, are commonly used on objects, but /type/object/type is never set to /type/object. Similarly, it is perfectly possible (and not uncommon) to define a /common/topic/alias property on an object without setting /type/object/type to /common/topic.

Also, the expected type of a property is only the expected type. The open and fluid nature of the Metaweb graph means that Metaweb cannot guarantee that the values of a property will always be members of the expected type.

                      +--/type/id
                      |
                      +--/type/int
                      |
                      +--/type/float
                      |
                      +--/type/boolean
                      |
      +--Value Types--+--/type/text
      |               |
      |               +--/type/rawstring
      |               |                     +--/restaurant domain
      |               +--/type/uri          |
      |               |                     +--/location domain
      |               +--/type/datetime     |
      |               |                     +--/film domain   +-/music/track
Types-+               +--/type/key          |                 |
      |                                     +--/music domain--+-/music/album
      |                                     |                 |
      |               +--Freebase Types-----+--/book domain   +-/music/artist
      |               |                     |
      |               |                     +--etc.
      |               |
      +--Object Types-+--Core Types (/type domain)    
                      |                     
                      +--Common Types (/common domain)
                      |                     
                      +--User-defined types-+--/user/joe/default_domain
                                            |
                                            +--/user/joe/music

Like many programming languages, Metaweb draws a distinction between objects and primitive values such as numbers, dates and strings. When we view the Metaweb graph as a set of tuples, we see that some tuples have a reference to another node in the To column and some have a primitive value in the Value column instead. If a property has an expected type that is a value type, then a tuple involving that property will have a value in the Value column. On the other hand, if a property has an expected type that is an object type then a tuple involving that property will have no value in the Value column.

Metaweb defines nine value types. Like all Metaweb types, value types are identified by type objects such as /type/int (for the value type that represents integer values). The sub-sections that follow explain each of the value types in detail. We begin, however, with a short discussion of value types and properties.

1.0       # integer and fractional part
1         # integer part alone
.0        # fractional part alone
-1        # minus sign allowed as first character
1E-5      # exponent: 1 × 10-5 or 0.00001
5.98e24   # weight of earth in kg: 5.98 × 1024

2001-01-01T00:00:00.001Z

2001                   # The year 2001
2001-01                # January 2001
2001-01-01             # January 1st 2001
2001-01-01T01Z         # 1 hour past midnight (UTC), January 1st 2001
2000-12-31T23:59Z      # 1 minute before midnight (UTC) December 31st, 2000
2000-12-31T23:59:59Z   # 1 second before midnight (UTC) December 31st, 2000
2000-12-31T23:59:59.9Z # .1 second before midnight (UTC) December 31st, 2000
00:00:00Z              # Midnight, UTC
12:15                  # Quarter past noon, local time
17-05:00               # Happy hour, Boston (US Eastern Standard Time)

This section covers the core object types in the /type domain, and also introduces commonly-used types from the /common domain and elsewhere. You do not need to understand these types in detail in order to make productive use of Metaweb. Still, knowing what these basic types are is a helpful orientation to the system. You can learn more about these (or any) Metaweb types at freebase.com. Learn about a type and its properties by appending the type id to the URL http://freebase.com/type/schema. To read more about the type /type/unit, for example, visit: http://freebase.com/type/schema/type/unit .

Metaweb is completely open for reading. Anyone who can connect to Metaweb servers can read data from them. When adding or editing data, however access control comes into play. We've already seen that the types /type/user, /type/usergroup, and /type/permission are used for access control.

Metaweb's access control model is quite simple. Every object has a permission property that refers to a /type/permission object. The permission object specifies a set of usergroups whose members have permission to modify the object. If a user is a member of one or more of the specified groups, then that user can edit ^[6] the object. Otherwise, the user is not allowed to.

This simple access control model is, by default, completely open. In order to allow and encourage free collaboration most Metaweb objects have a permission object that gives edit permission to all Metaweb users. If Metaweb user Fred creates a new object, his friend Jill can freely edit that object, and any other Metaweb user can edit the object as well. (In Chapter 6 we'll learn how to alter the default permission to create objects with restricted access.) The use of Metaweb types is also completely open: any user can create instances of any type, regardless of who "owns" the type.

Although most objects can be freely edited and all types can be freely used, Metaweb namespaces are not usually wide open like this. System namespaces like /lang and /type are owned by Metaweb administrators, and regular users cannot add keys to them. The most common user-defined namespaces are domains, which serve as the namespace for types, and types, which serve as the namespace for properties. When you create a new domain, a usergroup and permission object are created with it, and the permission property of the domain is set so that only members of the usergroup can define keys in the domain. This means that only members of the group can define types in the domain. Newly created types use the same permission object as their domain, which means that only users in the usergroup can define properties in the namespace of the type. The freebase.com client allows users to create personal domains, and to edit the membership of the associated usergroup. This allows Fred to create a new domain and then add Jill and other collaborators to the usergroup so that they can create and modify types within the domain.

We'll explore the topic of access control in more detail in Section 5.12 after we have learned how to express MQL write queries.