Skip to content

Data Access High level

Jump to bottom
Andy Johns edited this page Nov 15, 2017 · 22 revisions

Description: Data Access High level

Couchbase management and other high-level capabilities

For all calls described below databaseName must be the expected database name as configured for the application, or the tilde "~" character, which can be used to represent the configured database name in all DB service calls. If databasename is not yet created locally the database will be created at the time the call is made.

Replication Configuration

Method: POST

URL: http://pmapi/db/{databaseName}/replication

Optional Query: wait or wait=true Declaring wait will cause the DBService to not be complete until initial replication has occurred.

Input: JSON dictionary specifying the URL for replication:

{
    "replicationURL" : "https://myserver.com/mypath/databaseName"
}

Output: Standard HTTP status codes.

Replication will be automatically started, and will continue as long as the device has connectivity and is authenticated. If connectivity and/or authentication is lost, replication will resume once connectivity and authentication is reestablished. See Connectivity Service

Method: PUT

URL: http://pmapi/db/{databaseName}/replication/pull

Input: JSON dictionary specifying the service-side channels to add or remove from replication restrictions:

{
    "add" : ["channelOne", "channelTwo"]
    "remove" : ["channelThree", "channelFour"]
}

Alternatively the boolean value removeall:

{
    "removeall" : true
}

Either add, remove or both, or the removeall parameter must be included.

If removeall is included and true, and add or remove is also included, the add or remove will be ignored and all channels will be removed from the restrictions.

If removeall is included and not true, and add or remove is also included, the removeall will be ignored, and the add or remove values will be used to configure the channel restrictions.

If pull channels are configured before initial replication is setup (see POST above) then the channel configuration provided will be used for the default configuration when replication is first established.

Output: HTTP Status codes:

  • 200 (OK) if inputs are valid, and the channels configuration operation was successful.
  • 400 (Bad Request) if the input dictionary was missing, invalid, or did not contain expected parameters.

A word about channel configuration

Adding channels restricts the documents that are sent from the server to the client to only those documents associated with the configured channels. If no channels are configured, the user will receive all documents to which they have access. Because documents such as the pm-app document and the web-app documents are used in the general control of Predix Mobile, take care if using this channel restriction as you could cause the system to not replicate critical documents the system needs to function.

Method: PUT

URL: http://pmapi/db/{databaseName}/replication/push

Sets the active filter and parameters. Only one filter can be active at a time.

Input: JSON dictionary specifying the client-side filter to use in determining what documents to send to the server.

{
    "filter" : "myFilter"
    "parameters" : {"someKey": "someValue"}
}

The filter parameter is required, the parameters parameter is optional.

The filter parameter is the name of the filter, as defined within the Container code. The filter name must be predefined in the native code in order to use the filter.

The parameters parameter is supplied to the filter code when determining if a document should be replication from the client to the server. It must be a dictionary, with string type keys.

Output: HTTP Status codes:

  • 200 (OK) if inputs are valid, and the filter configuration operation was successful.
  • 400 (Bad Request) if the input dictionary was missing, invalid, did not contain expected parameters, or if the named filter was not defined in the native container code.

Filters are used to restrict what data is sent from the client to the server, a complement of channels. As such, filters should be used with caution, as if they are used incorrectly they could prevent needed information from flowing to the server.

Method: GET

URL: http://pmapi/db/{databaseName}/replication

Output: Standard HTTP status codes. 404 if Replication has not been configured yet. JSON dictionary containing information about replication status. Dictionary will contain two top-level elements: push and pull for the two replication directions. Each top-level element will contain a dictionary containing status, changesCount, and completedChangesCount.

Optionally, if there have been recent replication errors there may be the elements lastErrorCode and lastErrorDescription.

If a Push replication filter has been configured the push section will have the element filter and if parameters for that filter have been configured, parameters

If a list of Pull replication channels have been configured, the pull section will have a string array channels element

Possible values for the status element are:

  • Active
  • Idle
  • Offline
  • Stopped

Examples:

A normal replication status when no replication is occurring:

{
  "push" : {
              "status" : "Idle",
              "changesCount" : "0",  
              "completedChangesCount" : "0"
           }
  "pull" : {
              "status" : "Idle",
              "changesCount" : "0",  
              "completedChangesCount" : "0"
           }
}

A normal replication status an active replication is occurring:

{
  "push" : {
              "status" : "Active",
              "changesCount" : "10",  
              "completedChangesCount" : "3"
           }
  "pull" : {
              "status" : "Idle",
              "changesCount" : "0",  
              "completedChangesCount" : "0"
           }
}

A replication status after a problem:

{
  "push" : {
              "status" : "Idle",
              "changesCount" : "0",  
              "completedChangesCount" : "0"
              "lastErrorCode" : "123"
              "lastErrorDescription" : "This is a description of the push error"
           }
  "pull" : {
              "status" : "Idle",
              "changesCount" : "0",  
              "completedChangesCount" : "0"
              "lastErrorCode" : "123"
              "lastErrorDescription" : "This is a description of the pull error"
           }
}

A normal replication status when push filters, and pull channels have been configured

{
  "push" : {
              "status" : "Idle",
              "changesCount" : "0",  
              "completedChangesCount" : "0",
              "filter" : "MyFilter",
              "parameters" : {"parameterOne" : "someValue"}
           }
  "pull" : {
              "status" : "Idle",
              "changesCount" : "0",  
              "completedChangesCount" : "0",
              "channels" : ["channelOne", "channelTwo"]
           }
}
Document Create, Read, Update, Delete

Method: POST Not yet supported in Java or Android.

URL: http://pmapi/db/{databaseName}/document/{documentId}

Input: JSON dictionary

If URL does not include {documentId}, document will be created with either a random document id, or if input dictionary contains a key "_id" it, this value will be used as the document id.

Output: Status code 201 on successfully creating the document. Document JSON will be returned on success.

Otherwise standard error status codes.

Method: GET

URL: http://pmapi/db/{databaseName}/document/{documentId}

Output: Standard HTTP status codes and JSON of properties from document with id of {documentId}.

Method: PUT Not yet supported in Java or Android.

URL: http://pmapi/db/{databaseName}/document/{documentId}

Input: JSON dictionary

Replaces the contents of the {documentId} document with the provided JSON dictionary.

Output: Status code 200, on successfully updating the document. Document JSON will be returned on success.

Otherwise standard error status codes.

Method: DELETE Not yet supported in Java or Android.

URL: http://pmapi/db/{databaseName}/document/{documentId}

Output: Status code 200, on successfully deleting the document.

Otherwise standard error status codes.

Document retrieval by type

Method: GET

URL: http://pmapi/db/{databaseName}/type/{type}

Output: Standard HTTP status codes and JSON array of properties from documents with type of {type}.

Querying Views

Not yet supported in Java or Android.

Method: POST

URL: http://pmapi/db/{databaseName}/query/{view}

Every path component after the query is considered part of the view name. Thus, the {view} name may include slashes. For example views/myview is a valid view name and a URL request to that view would be:

http://pmapi/db/~/query/views/myview

Input: Optional JSON dictionary specifying the parameters for the query:

Input keys:

  • sortOrder: String value either ascending or descending. If not provided, defaults to ascending
  • limitRows: Integer value specifying the maximum number of result rows to return. Defaults to all rows.
  • skipRows: Integer value specifying the number of rows in the result set to skip before returning rows. Defaults to zero. Can be used with limitRows provide paging behavior.
  • keys: An array of keys to match in the view. When used, only rows matching the provided keys will be returned. Cannot be combined with startKey and endKey.
  • startkey: Will start returning rows matching this key, according to the sortOrder. Can be used with endkey. Cannot be combined with keys. If not provided will start with the first row in the result set.
  • endkey: Will stop returning rows matching this key, according to the sortOrder. Can be used with startkey. Cannot be combined with keys. If not provided will end with the last row in the result set.
  • includeDocuments: Boolean value indicating full documents should be returned with the result rows.
  • script: A JavaScript function to call when the results of the query change. If provided, the query parameters will contined to be monitored in the background, and should the data in the database change so the result of the query changes, the provided JavaScript function will be called with the new query results.
  • notificationName: Can optionally be used with the script parameter, allowing multiple subscribed queries to call the same JavaScript function.

Notes:

If includeDocuments is used, the entire document will be included with every query output row. This could cause the resulting query results to be quite large. This should be used only if you truely need the full document contents from every document in the result set. It is often more effecient to ensure the document values you need are included in the value of the view index, or to seperately request a subset of specific documents from the result output.

Using script will establish a subscription for the query in the background on the device. Background running queries consume system resources, and should be used sparingly to conserve battery, CPU, and memory. The query subscription should be cleaned up by sending a DELETE request when the query subscription is no longer needed. Subscribing querys use the same Notificaiton subsystem as the Notify service, so all rules and functionality for the script parameter that apply to the event Notify service, also apply to the query notifification.

If a script parameter is provided, but not a notificationName parameter, the a value of the script parameter is used as the notification name. If the script parameter contains parentheses, the notfication name will be the substring of the script parameter up to the open parentheses ( character. Knowing the notificationName is important, because it is required when unsubscribing to the query notification (see DELETE below.)

The notificationName must be globally unique. Subscribing to two views using the same notificationName will result in the second subscription replacing the first.

A notificationName parameter without a script parameter will be ignored.

Output: Standard HTTP status codes.

If the {view} path component specified does not exist a 404 would be returned. If no {view} path component is in the URL, then a 400, bad request is returned.

If no JSON dictionary is POSTed, or the JSON dictionary cannot be parsed, the results will be the entire data set for the view.

The resulting output will be a JSON dictionary containing these keys:

  • error: If an error occured during the query, this will be a string containing error details.

  • offset: The offset into the total result data rows, as specified by the input skipRows parameter

  • count: Number of rows in the returned result set

  • includesDocuments: Boolean value as specified by the input includeDocuments parameter, indicating documents are or are not included in the result rows.

  • rows: Array of JSON dictionaries containing the query results with these keys:

    • id: The document id of the document related to this row. If the view for this query contained a map/reduce function this element may not be included, if there is no direct document associated with each row.
    • key: The view's key for this row, as specifed by the view definition.
    • value: The view's value for this row, as specified by the view definition. If the view did not define a value this element will not be included.
    • doc: The document contents associated with this row, if the includeDocuments parameter was true in the query parameter input. Like the id element, if the view for this query contained a map/reduce function this element may not be included if there is no direct document associated with each row.

See Also: See also, native view creation:

Examples:

Given a native code view called foods that emits a key field of type and a value field of name

Where the database contains document data according to this table

id type name
item-1 fruit apple
item-2 veg cabbage
item-3 fruit banana
item-4 meat chicken
item-5 veg cucumber
item-6 meat beef
item-7 veg zucchini
item-8 meat salmon

Then to create a query that will return data from documents whose type is either fruit or meat

  • Request:

    POST http://pmapi/db/~/query/foods

    POST body:

     {
 	"keys": ["fruit", "meat"]
 }

  • Response Status: 200 OK

  • Response JSON:

	{
	    "offset": 0,
   	    "count": 5,
   	    "includesDocuments": false,
	    "rows": [
	        {
	            "id": "item-1",
	            "key": "fruit",
	            "value": "apple"
	        },
	        {
	            "id": "item-3",
	            "key": "fruit",
	            "value": "banana"
	        },
	        {
	            "id": "item-4",
	            "key": "meat",
	            "value": "chicken"
	        },
	        {
	            "id": "item-6",
	            "key": "meat",
	            "value": "beef"
	        },
	        {
	            "id": "item-8",
	            "key": "meat",
	            "value": "salmon"
	        }
	    ]
	}

Similarly, if the POST body was:

	{
		"startkey": "m"
		"script": "foodsUpdated"
	}
  • Response Status: 200 OK
  • Response JSON:
	{
	    "offset": 0,
   	    "count": 6,
   	    "includesDocuments": false,
	    "rows": [
	        {
	            "id": "item-4",
	            "key": "meat",
	            "value": "chicken"
	        },
	        {
	            "id": "item-6",
	            "key": "meat",
	            "value": "beef"
	        },
	        {
	            "id": "item-8",
	            "key": "meat",
	            "value": "salmon"
	        },
	        {
	            "id": "item-2",
	            "key": "veg",
	            "value": "cabbage"
	        },
	        {
	            "id": "item-5",
	            "key": "veg",
	            "value": "cucumber"
	        },
	        {
	            "id": "item-7",
	            "key": "veg",
	            "value": "zucchini"
	        }
	    ]
	}

If then new document is added to the database:

id type name
item-9 meat pork

The JavaScript function foodsUpdated would be called, with a JSON parameter containing:

	{
	    "offset": 0,
   	    "count": 7,
   	    "includesDocuments": false,
	    "rows": [
	        {
	            "id": "item-4",
	            "key": "meat",
	            "value": "chicken"
	        },
	        {
	            "id": "item-6",
	            "key": "meat",
	            "value": "beef"
	        },
	        {
	            "id": "item-8",
	            "key": "meat",
	            "value": "salmon"
	        },
	        {
	            "id": "item-9",
	            "key": "meat",
	            "value": "pork"
	        },	        
	        {
	            "id": "item-2",
	            "key": "veg",
	            "value": "cabbage"
	        },
	        {
	            "id": "item-5",
	            "key": "veg",
	            "value": "cucumber"
	        },
	        {
	            "id": "item-7",
	            "key": "veg",
	            "value": "zucchini"
	        }
	    ]
	}

Method: DELETE

URL: http://pmapi/db/{databaseName}/query/{view}/{notificationName}

Unsubscribes and stops monitoring the query related to the specified view notification. The provided notificationName is the notification name provided when the view query was subscribed to in the notificationName parameter, or was derived from the script parameter. (See POST above)

Method: DELETE

URL: http://pmapi/db/{databaseName}/query

Unsubscribes and stops monitoring the queries related to all view notifications currently registered in the system.

Shutting down Couchbase

Method: POST

URL: http://pmapi/db/close

Output: Standard HTTP status codes.

Closes the local Couchbase manager and cleans up all associated objects. Any replication is stopped and replication objects are cleaned up.

Document attachment retrieval

Method: GET

URL: http://pmapi/db/{databaseName}/attachments/{documentId}

Output: Standard HTTP status codes and JSON indicating success and path of attachment file:

{
    "ok" : "true"
    "attachments_path" : "root_path_to_unzipped_attachments"
}
Adding attachments

Method: POST

URL: http://pmapi/db/{databaseName}/attachments/{documentId}

Input: HTTP Body contains dictionary with following key/values:

Headers: The request header "Content-Type" should be set to the value "application/json" (e.g. "Content-Type: application/json")

  • contenttype: MIME Content type of attachment
  • name: Optional name to use for attachment. Defaults to filename in URL if not provided
  • url: URL of attachment. (Note: On iOS, can be a local or remote URL, e.g. file://, http://, etc.).

{OR}

URL: http://pmapi/db/{databaseName}/attachments/{documentId}?contenttype={type}&name={name.ext}

Input: HTTP Body contains raw binary data of attachment

Headers: The request header "Content-Type" should be set to the value "application/octet-stream" (e.g. "Content-Type: application/octet-stream")

Query String Parameters:
  • contenttype: MIME Content type of attachment
  • name: Name to use for attachment.

Output:

  • 201 - New attachment created. Data return will be properties of document
  • 400 - Bad request, path or HTTP body values are incorrect
  • 404 - {documentId} was not found
  • 500 - Error saving attachment. Error description will be in data return.

Intro *Home

Services

iOS SDK

iOS Examples

Java Examples

General

[//]: (Enabling Sync Logging)

Clone this wiki locally