Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Document Access with Edge Server

    You can create, read, update, and delete documents in a keyspace using the REST API’s document operations.

    Scopes and Collections

    Within a database, documents are organized using scopes and collections. A database contains one or more scopes, and each scope may contain one or more collections. All documents are stored within a collection.

    Each database contains a default scope called _default, which contains a default collection, also called _default. A database may contain other named, non-default scopes and collections as required.

    For more information about scopes and collections, see Manage Scopes and Collections.

    Keyspace References

    When working with documents, you must specify the database, scope and collection where the documents are stored. To do this, you must provide a keyspace reference to the REST API.

    • For a named scope and collection, the keyspace reference consists of the database name, followed by the scope name and the collection name, separated by periods (.). For example, travel-sample.inventory.airport.

    • For a named collection within the default scope, you can omit the scope name from the keyspace reference. For example, travel-sample.my_records refers to the my_records collection within the default scope in the travel-sample database.

    • For the default scope and collection, you can omit both the scope name and the collection name from the keyspace reference. For example, travel-sample refers to the default collection within the default scope in the travel-sample database.

    Document Structure

    In Edge Server, the content of each document is a JSON object. Each document has metadata, which includes the document ID and revision number. Documents can have subdocuments and binary attachments.

    For more information about documents, see Documents. For more information about binary attachments, see Blobs.

    Examples

    In the command line examples:

    • $USER and $PASSWORD are the credentials for Couchbase Edge Server.

    • $CERT is the name and path to a TLS certificate file, for example cert.cer.

    • $HOST and $PORT are the host and port to connect to Couchbase Edge Server, for example localhost:59840.

    • $DOCID is the ID of a document, for example ~SCH2oNtKFMBdcO-_sUhBmn.

    • $REV is a revision number, for example 1-22855783cf597c31c37ec3815d8027f3706ef6f9.

    The following cURL examples use a self-signed TLS server certificate. In production, use a TLS certificate from a well-known certificate authority.

    Create a Document

    The following request creates a new document in the specified keyspace.

    HTTP Request
    curl --user $USER:$PASSWORD --cacert $CERT \
  "https://$HOST:$PORT/travel-sample.inventory.airport" \
  --json '{
  "type": "airport",
  "country": "United Kingdom",
  "icao": "EGOV",
  "airportname": "Anglesey Airport",
  "city": "Valley",
  "faa": "VLY",
  "tz": "Europe/London"
}'

    The response is a JSON object similar to the following. In this case, Edge Server generates an ID for the document automatically.

    HTTP Response
    {
  "ok": true,
  "id": "~SCH2oNtKFMBdcO-_sUhBmn",
  "rev": "1-22855783cf597c31c37ec3815d8027f3706ef6f9"
}

    You can use the generated document ID to read, update, or delete the same document. You must use the document revision number for concurrency control.

    Read a Document

    The following request gets the specified document in the specified keyspace.

    HTTP Request
    curl --user $USER:$PASSWORD --cacert $CERT \
  "https://$HOST:$PORT/travel-sample.inventory.airport/$DOCID"

    The response is a JSON object similar to the following. The response contains the document ID and revision number, as well as the document content.

    HTTP Response
    {
  "_id": "~SCH2oNtKFMBdcO-_sUhBmn",
  "_rev": "1-22855783cf597c31c37ec3815d8027f3706ef6f9",
  "type": "airport",
  "country": "United Kingdom",
  "icao": "EGOV",
  "airportname": "Anglesey Airport",
  "city": "Valley",
  "faa": "VLY",
  "tz": "Europe/London"
}

    Update a Document

    The following request checks whether the specified document within the specified keyspace has the expected revision number. If so, it adds a geo subdocument to the document.

    This ensures that you’re applying your update to the latest revision of the document, in cases where the document may be updated by other processes concurrently.

    HTTP Request
    curl -XPUT --user $USER:$PASSWORD --cacert $CERT \
  "https://$HOST:$PORT/travel-sample.inventory.airport/$DOCID/geo?rev=$REV" \
  --json '{
  "lat": 53.248056,
  "lon": -4.535278,
  "alt": 37
}'

    If the revision number of the document matches, the response is a JSON object similar to the following. The response contains the new revision number.

    HTTP Response
    {
  "ok": true,
  "id": "~SCH2oNtKFMBdcO-_sUhBmn",
  "rev": "2-51cb776222e4a366e8961e1c9fc09edddc5b0fa1"
}

    If the revision number does not match, the request returns a 409 error. If this happens, get the latest revision number for the document and try again.

    Set a Document Expiration

    When a document expires, Edge Server purges it from the database and leaves no tombstone.

    Expiration only removes the document from Edge Server. Edge Server does not replicate the purge, so if you replicate with App Services or Sync Gateway, the document stays on the remote database. If the remote document changes later, Edge Server pulls the new revision and the document reappears. To remove a document everywhere, delete it instead. A delete creates a tombstone, which replicates.

    To set an expiration, add one of the following query parameters when you create a document or update a whole document.

    Table 1. Expiration Query Parameters
    Parameter Type Description

    ttl

    Integer

    The number of seconds from the time of the request until the document expires.

    expires

    Integer

    The time when the document expires, as a Unix timestamp in seconds. For example, 1798761600 is 00:00 UTC on January 1, 2027.

    If you set both parameters, Edge Server uses whichever expiration time is earlier.

    If you update a document without ttl or expires, the document keeps its existing expiration.

    You set expiration with query parameters, not with fields in the request body. Edge Server doesn’t read fields such as _exp or expiration from the body to set an expiration.

    For more information, see Edge Server Public REST API.

    The following request creates a new document in the specified keyspace, and sets the document to expire one hour after the request.

    HTTP Request
    curl --user $USER:$PASSWORD --cacert $CERT \
  "https://$HOST:$PORT/travel-sample.inventory.airport?ttl=3600" \
  --json '{
  "type": "airport",
  "country": "United Kingdom",
  "icao": "EGOV",
  "airportname": "Anglesey Airport",
  "city": "Valley",
  "faa": "VLY",
  "tz": "Europe/London"
}'

    The response is a JSON object similar to the following. The expires property shows the expiration time as a Unix timestamp in seconds.

    HTTP Response
    {
  "ok": true,
  "id": "~SCH2oNtKFMBdcO-_sUhBmn",
  "rev": "1-22855783cf597c31c37ec3815d8027f3706ef6f9",
  "expires": 1793451600
}

    The following request checks whether the specified document within the specified keyspace has the expected revision number. If so, it replaces the document content and sets the document to expire at 00:00 UTC on January 1, 2027.

    HTTP Request
    curl -XPUT --user $USER:$PASSWORD --cacert $CERT \
  "https://$HOST:$PORT/travel-sample.inventory.airport/$DOCID?rev=$REV&expires=1798761600" \
  --json '{
  "type": "airport",
  "country": "United Kingdom",
  "icao": "EGOV",
  "airportname": "Anglesey Airport",
  "city": "Valley",
  "faa": "VLY",
  "tz": "Europe/London"
}'

    If the revision number of the document matches, the response is a JSON object similar to the following.

    HTTP Response
    {
  "ok": true,
  "id": "~SCH2oNtKFMBdcO-_sUhBmn",
  "rev": "2-51cb776222e4a366e8961e1c9fc09edddc5b0fa1",
  "expires": 1798761600
}

    Delete a Document

    The following request checks whether the specified document within the specified keyspace has the expected revision number. If so, it deletes the document.

    This ensures that you’re deleting the latest revision of the document, in cases where the document may be updated by other processes concurrently.

    HTTP Request
    curl -XDELETE --user $USER:$PASSWORD --cacert $CERT \
  "https://$HOST:$PORT/travel-sample.inventory.airport/$DOCID?rev=$REV"

    If the revision number of the document matches, the document is deleted. Edge Server returns a revision number for the deletion itself.

    HTTP Response
    {
  "ok": true,
  "id": "~SCH2oNtKFMBdcO-_sUhBmn",
  "rev": "3-b76bfea54ebb8e0337998d1ab591d9b19e238551"
}

    If the revision number does not match, the request returns a 409 error. If this happens, get the latest revision number for the document and try again.

    See Also