Compose Database-as-a-Service Help and Documentation

Everything you need to know about Compose, Hosted or Enterprise, is here in our help system. Whether you run one database for your businesses' sole application or six different databases to support an entire corporation, we've got the information you need.

MongoDB Documents

❗️

This is the older REST API and is now deprecated.

Go to the dedicated apidocs.compose.com for details of the current API which works with all Compose databases with the exception of the MongoDB Classic deployments.

📘

Base URL

All MongoDB document endpoint URLs begin with:

/deployments/:account/:deployment/mongodb/:database/collections/:collection

To improve readability, we’ve substituted a . for this string in the descriptions below.

EndpointDescription
GET ./documentsFind documents
GET ./documents/:documentFind one document
POST ./documentsCreate a document
PUT ./documents/:documentReplace a document
PATCH ./documentsBulk update documents
DELETE ./documents/:documentDelete a document
DELETE ./documentsDelete multiple documents

Common Parameters

ParamDescription
:accountAn account slug
:deploymentA deployment id or name
:databaseThe name of a database on :deployment
:collectionThe name of a collection in :database
:documentA URL-encoded JSON object (see below)

📘

How to encode the :document parameter

Anywhere you see :document below you should substitute a URL-encoded MongoDB Extended JSON object specifying the query you’re using to find a document or list of documents. For example:

encodeURIComponent('{"_id":{"$oid":"521d186b4165fd0d5500006f"}}');

GET ./documents

GET /deployments/:account/:deployment/mongodb/:database/collections/:collection/documents

List or query documents under the specified collection. Returns the documents in MongoDB Extended JSON format.

Parameters

NameTypeDescription
queryStringURL-encoded MongoDB Extended JSON document to use in querying your data
fieldsObjectA JSON document describing the fields to return from the query. See projection.
skipIntegerAn integer with the number of documents to skip, allowing pagination
limitIntegerThe number of documents to return, defaults to 10, max of 100
sortObjectA JSON document describing how to sort the results. See cursor.sort().
explainBooleanBoolean flag to run the explain command on the supplied inputs
include_statsBooleanBoolean flag to include statistics about the request, if true, JSON response will contain docs array field containing the matched documents, elapsed field containing the microseconds it took to process the query, count field containing the number of docs returned, and query field containing the string representationg of the query
secondary_prefBooleanBoolean flag to set secondary read preference. See read preference.

Request

curl -i -X GET 'https://api.compose.io/deployments/your-account/deployment-1/mongodb/database-1/collections/collection-name/documents?limit=10' \
-H 'Content-Type: application/json' \
-H 'Accept-Version: 2014-06' \
-H 'Authorization: Bearer [OAUTH_TOKEN]'

Response

[
  {
    _id: {
      $oid: "52d87a3cee2e6107ab000041"
    },
    created_at: {
      $date: 1389918780147
    },
    // ...
  },
  // 9 more documents
]

GET ./documents/:document

GET /deployments/:account/:deployment/mongodb/:database/collections/:collection/documents/:document

Retrieves a particular document by _id under the specified collection.

Request

curl -i -X GET 'https://api.compose.io/deployments/your-account/deployment-1/mongodb/database-1/collections/collection-name/documents/%7B%22_id%22%3A%7B%22%24oid%22%3A%22521d186b4165fd0d5500006f%22%7D%7D' \
-H 'Content-Type: application/json' \
-H 'Accept-Version: 2014-06' \
-H 'Authorization: Bearer [OAUTH_TOKEN]'

Response

{
  _id: {
    $oid: "52d87a3cee2e6107ab000041"
  },
  created_at: {
    $date: 1389918780147
  },
  // ...
}

POST ./documents

POST /deployments/:account/:deployment/mongodb/:database/collections/:collection/documents

Creates a new document with the document specified. There is no need to pass an _id as this will be generated automatically.

Parameters

NameTypeDescription
documentObjectMongoDB Extended JSON document to be created.

Request

curl -i -X POST 'https://api.compose.io/deployments/your-account/deployment-1/mongodb/database-1/collections/collection-name/documents' \
-H 'Content-Type: application/json' \
-H 'Accept-Version: 2014-06' \
-H 'Authorization: Bearer [OAUTH_TOKEN]' \
-d '{"document":{"_id":"elton","pilot_name":"Elton John"}}'

Response

{
  "ok": 1
}

PUT ./documents/:document

PUT /deployments/:account/:deployment/mongodb/:database/collections/:collection/documents/:document

Replace a single document by _id under the specified collection.

Parameters

NameTypeDescription
documentObjectMongoDB Extended JSON document to be created.

Request

curl -i -X PUT 'https://api.compose.io/deployments/your-account/deployment-1/mongodb/database-1/collections/collection-name/documents/%7B%22_id%22%3A%7B%22%24oid%22%3A%22521d186b4165fd0d5500006f%22%7D%7D' \
-H 'Content-Type: application/json' \
-H 'Accept-Version: 2014-06' \
-H 'Authorization: Bearer [OAUTH_TOKEN]' \
-d '{"document":{"pilot_name":"Rocket Man"}}'

Response

{
  "ok": 1
}

PATCH ./documents

PATCH /deployments/:account/:deployment/mongodb/:database/collections/:collection/documents

Update documents by criteria. Also known as bulk update. You can pass any JSON criteria and new object that is accepted by the update command in MongoDB.

Parameters

NameTypeDescription
criteriaObjectMongoDB Extended JSON document criteria used to match which documents to update.
updateObjectMongoDB Extended JSON document update command (accepts standard MongoDB update directives, like $set or $inc).
upsertBooleanIf set to true, the operation will create records that do not exist. Upsert only inserts a single document. (defaults to false)
multiBooleanIf set to true, all documents matching the criteria should be updated. false* will update just one. (defaults to false)

Request

curl -i -X PATCH 'https://api.compose.io/deployments/your-account/deployment-1/mongodb/database-1/collections/collection-name/documents' \
-H 'Content-Type: application/json' \
-H 'Accept-Version: 2014-06' \
-H 'Authorization: Bearer [OAUTH_TOKEN]' \
-d '{"criteria":{"pilot_name":"Rocket Man"},"update":{"$set":{"pilot_name":"Elton John"}}}'

Response

{
  "ok": 1
}

DELETE ./documents/:document

DELETE /deployments/:account/:deployment/mongodb/:database/collections/:collection/documents/:document

Destroy a single document by id under the specified collection. Be careful, as this operation cannot be undone.

Request

curl -i -X DELETE 'https://api.compose.io/deployments/your-account/deployment-1/mongodb/database-1/collections/collection-name/documents/%7B%22_id%22%3A%7B%22%24oid%22%3A%22521d186b4165fd0d5500006f%22%7D%7D' \
-H 'Content-Type: application/json' \
-H 'Accept-Version: 2014-06' \
-H 'Authorization: Bearer [OAUTH_TOKEN]'

Response

{
  "ok": 1
}

DELETE ./documents

DELETE /deployments/:account/:deployment/mongodb/:database/collections/:collection/documents

Destroy multiple documents by criteria under the specified collection. Be careful as this operation cannot be undone.

Parameters

NameTypeDescription
criteriaObjectMongoDB Extended JSON document criteria used to match which documents to update.
just_oneBooleanIf set to true, the operation will only delete the first record it comes to based on the criteria. (defaults to false)
delete_allBooleanIf set to true, all documents matching the criteria should be deleted. This is essentially a safety mechanism should you accidentally pass in an empty criteria which would delete ALL documents in the collection. (defaults to false)

Request

curl -i -X DELETE 'https://api.compose.io/deployments/your-account/deployment-1/mongodb/database-1/collections/collection-name/documents' \
-H 'Content-Type: application/json' \
-H 'Accept-Version: 2014-06' \
-H 'Authorization: Bearer [OAUTH_TOKEN]' \
-d '{"criteria":{"pilot_name":"Elton John"},"delete_all":true}'

Response

{
  "ok": 1
}

Still Need Help?

If this article didn't solve things, summon a human and get some help!

Updated about a year ago

MongoDB Documents


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.