Basic Concepts

Documents

The basic unit of organization in MarkLogic is a Document and the REST API enables you to store and search documents. The REST API supports documents encoded in JSON like

{ name: 'Asahi Draft Beer', brewer: { name: 'Asahi', country: 'Japan' }, calories: 41, alcohol: '5.21' }

and XML like

<beer> <name>Asahi Draft Beer</name> <brewer> <name>Asahi</name> <country>Japan</country> </brewer> <calories>41</calories> <alcohol>5.21</alcohol> </beer> The set of JSON keys, objects, and arrays, or XML elements and attributes you use in your documents is up to you. MarkLogic does not require adherence to any schemas.

MarkLogic also supports documents encoded in binary form or plain text as well. We refer to this encoding (JSON, XML, text, or binary) as the document's Format.

URIs

A document's URI is a key that you choose when you insert a document into the database. Each document has a unique URI. You use this URI to retrieve or refer to the document later. Typically document URIs begin with a slash like /beer.

Beyond the URI, MarkLogic maintains some additional metadata associated with each document including properties, permissions, and quality.

Organization

How does MarkLogic organize documents in the database? Logically, MarkLogic provides two concepts: Collections and Directories. You can think of collections as unordered sets. If you have a notion of tag as well, that may help. Collections can hold multiple documents and documents can belong to multiple collections.

Directories are similar in concept to the notion of directories or folders in file systems. They are hierarchical and membership is implicit based on the path syntax of URIs.

 

API basics

Ok, so that's what is stored in MarkLogic. What do the APIs look like? MarkLogic REST Client endpoints are of the form:

http://host:port/version/service/...

The part of the URL to left of the first single slash (http://host:port) will be given to you by your database administrator.

The service name starts the rest of the URL path and is indicative of what the service does. The part of the URL that follows (/... above) is used to provide additional parameters to the service. Sometimes these are additional components of the path. Sometimes there are additional query string variables.

You will also need some credentials (username and password) to access the server. You should get these from your database administrator as well. (See the REST API setup screencast for details).