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

    March 30, 2025
    + 12
    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 on 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.airports.

    • 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 on documents, see Documents. For more information on 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.

    Note that the following cURL examples use a self-signed TLS server certificate. In production, you are strongly recommended to use a TLS certificate generated by a well-known authority.

    Create a Document

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

    HTTP Request
    sh
    Copy
    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
    json
    Copy
    {
  "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
    sh
    Copy
    curl --user $USER:$PASSWORD --cacert $CERT \
  "https://$HOST:$PORT/travel-sample.inventory.airport/$DOCID"

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

    HTTP Response
    json
    Copy
    {
  "_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
    sh
    Copy
    curl -XPUT $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. Note that the revision has been updated.

    HTTP Response
    json
    Copy
    {
  "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.

    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
    sh
    Copy
    curl -XDELETE $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. Note that Edge Server returns a revision number for the deletion itself.

    HTTP Response
    json
    Copy
    {
  "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