David Flanagan, November 22, 2008

MQL Reference Guide

Table of Contents

1. Introduction
1.1. The Metaweb Query API
1.2. About this Manual
2. Metaweb Architecture
2.1. Nodes and Relationships
2.2. Properties
2.2.1. Properties and Uniqueness
2.2.2. Properties and Direction
2.2.3. Properties and Meaning
2.3. Names, Identifiers and Namespaces
2.4. Objects and Types
2.4.1. Universal Properties
2.4.2. Types and Domains
2.5. Value Types
2.5.1. Properties of Value Types
2.5.2. /type/int
2.5.3. /type/float
2.5.4. /type/boolean
2.5.5. /type/text
2.5.6. /type/rawstring
2.5.7. /type/uri
2.5.8. /type/datetime
2.5.9. /type/key
2.5.10. /type/id
2.6. Object Types
2.6.1. Core Types
2.6.2. Common Types
2.7. Access Control
3. The Metaweb Query Language
3.1. JavaScript Object Notation
3.1.1. JSON Literals: null, true, false
3.1.2. JSON Numbers
3.1.3. JSON Strings
3.1.4. JSON Arrays
3.1.5. JSON Objects
3.2. Basic MQL Queries
3.2.1. Our First Query
3.2.2. Query/Response Symmetry
3.2.3. Object IDs
3.2.4. Multiple Results and Uniqueness Errors
3.2.5. Nested Sub-queries
3.2.6. Inverting Queries
3.2.7. Asking Metaweb For Objects
3.2.8. Expanded Values and Default Properties
3.2.9. Review: Asking for Values
3.3. Names, Ids, Keys and Namespaces
3.3.1. Names and Per-Language Uniqueness
3.3.2. Ids
3.3.3. Keys and Namespaces
3.3.4. Namespaces and Uniqueness
3.3.5. Enumerations
3.3.6. GUIDs
3.4. Property Names in MQL Queries
3.4.1. Simple and Qualified Property Names
3.4.2. Property Prefixes
3.4.3. Wildcards
3.4.4. Inverting a Property with !
3.4.5. Property Objects
3.5. MQL Directives
3.5.1. Limiting Results
3.5.2. Counting Results
3.5.3. Sorting Results
3.5.4. Ordered Collections
3.5.5. Optional Matches
3.5.6. Forbidden Matches
3.6. MQL Operators
3.6.1. Order Constraints
3.6.2. Pattern Matching with the ~= Operator
3.6.3. The "one of" Operator |=
3.6.4. The "but not" Operator !=
3.6.5. Expressing AND, OR, and NOT in MQL
3.7. Links, Reflection and History
3.7.1. Links to Sub-queries
3.7.2. Toplevel Links
3.7.3. Reflection
3.7.4. History
4. Metaweb Read Services
4.1. Basic mqlread Queries with Perl
4.1.1. A Better Perl Album Lister
4.2. The mqlread Service
4.2.1. The query Request Parameter
4.2.2. The queries Request Parameter
4.2.3. The Response Envelope
4.2.4. Envelope Parameters
4.2.5. The callback Request Parameter
4.2.6. mqlread Error Codes
4.3. A Python Album Lister
4.4. A Metaweb-enabled PHP Application
4.5. Metaweb Queries with JavaScript
4.5.1. Invoking mqlread with the jQuery Library
4.5.2. Listing Albums and Tracks with JavaScript
4.5.3. Client-side MQL Queries with <script>
4.6. The Metaweb Search Service
4.6.1. Search Input
4.6.2. Search Output
4.6.3. Example: Searching for Band Names
4.7. Fetching Content with trans
4.7.1. JavaScript Functions for Downloading Content
4.7.2. Example: What's New on freebase.com
4.7.3. Example: A Metaweb Type Browser
4.8. Metaweb Services with Python
5. The MQL Write Grammar
5.1. Creating a Type to Work With
5.2. Creating Objects
5.3. Connecting Objects
5.4. Disconnecting Objects
5.5. Writes and Default Properties
5.5.1. Caution: unless_exists with Expanded Objects
5.6. Creating and Connecting More Objects
5.7. Review: Write Directives
5.8. Working with Sets
5.9. Reciprocal Properties
5.10. Writes and Ordered Collections
5.11. Namespaces and Enumerations
5.11.1. The /type/namespace/keys Property
5.11.2. Fully-Qualified Names and Uniqueness
5.11.3. Enumerations
5.12. Access Control and Permissions
5.12.1. Users, Usergroups and Permissions
5.12.2. Per-Object Access Control
5.12.3. Per-Property Access Control
6. Metaweb Write Services
6.1. Logging in to Metaweb
6.2. Making Write Queries
6.2.1. Using mqlwrite With Python
6.2.2. Example: US State Quarters
6.2.3. Sending Multiple Queries to mqlwrite
6.2.4. Mqlwrite Envelope Parameters
6.2.5. The X-Metaweb-Request Header
6.2.6. Caching: mwLastWriteTime and Touch
6.3. Uploading Data to Metaweb
6.3.1. An Upload Utility
6.3.2. Examples: Uploading Images of State Quarters
6.3.3. Uploading Documents

List of Examples

4.1. albumlist.pl: submitting MQL queries in Perl
4.2. albumlist2.pl: a better Perl album lister
4.3. albumlist.py: listing albums with Python
4.4. metaweb.php: using mqlread with PHP
4.5. albumlist.php: A Metaweb-enabled web application in PHP
4.6. simplelist.html: Listing albums with jQuery
4.7. albumlist.html: a JavaScript album and track lister
4.8. metaweb.js: Metaweb queries with script tags
4.9. metaweb.js: searching Metaweb
4.10. albumlist2.html: Searching for bands
4.11. metaweb.js: an extension for the trans service
4.12. WhatsNew.html: fetching new images and documents from freebase.com
4.13. TypeBrowser.html: a Metaweb type browser
4.14. Using the metaweb.py module to read, search and download
4.15. metaweb.py: a Python module for Metaweb
6.1. metaweb.py: the login service
6.2. metaweb.py: invoking the mqlwrite service
6.3. quarters.py: writing a data set to Metaweb
6.4. metaweb.py: invoking the touch service
6.5. metaweb.py: uploading content to Metaweb
6.6. quarterpix.py: uploading images to Metaweb
6.7. uploaddoc.py: uploading HTML documents to Metaweb