—Rate this article—
 

Updating Collections

This article describes how to perform batch updates on all entities in a collection. Batch updates require the use of a query string in the request, which can either specify all entities in the collection or a subset of entities for the update to be performed on. For more information on queries, see Querying your data.

Note: Although not shown in the API examples below, you need to provide a valid access token with each API call. See Authenticating users and application clients for details.

Batch updating entities in a collection

Request Syntax

curl -X PUT https://api.usergrid.com/<org>/<app>/<collection>/?ql= -d {<property>}

Note the empty query string (ql=) appended to the URL.

Parameters

Parameter Description
org Organization UUID or organization name
app Application UUID or application name
collection Collection UUID or collection name
property

An entity property to be updated, formatted as a key-value pair. For example:

{"property_1":"value_1", "property_2":"value_2",...}

Example Request/Response

Request:

curl -X PUT https://api.usergrid.com/your-org/your-app/items/?ql= -d '{"availability":"in-stock"}'

Note the empty ?ql= query string.

Response:

{
  "action" : "put",
  "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
  "params" : {
    "ql" : [ "" ]
  },
  "path" : "/items",
  "uri" : "http://api.usergrid.com/your-org/your-app/items",
  "entities" : [ {
    "uuid" : "31847b9a-1a62-11e3-be04-8d05e96f700d",
    "type" : "item",
    "name" : "milk",
    "price" : "3.25",
    "availability" : "in-stock"
    "created" : 1378849479113,
    "modified" : 1378849567301,
    "name" : "milk",
  }, {
    "uuid" : "3192ac6a-1a62-11e3-a24f-496ca1d42ce7",
    "type" : "item",
    "name" : "bread",
    "price" : "4.00",
    "availability" : "in-stock"
    "created" : 1378849479206,
    "modified" : 1378849567351,
    "name" : "bread",
  } ],
  "timestamp" : 1378849567280,
  "duration" : 207,
  "organization" : "your-org",
  "applicationName" : "your-app"
}

This example uses the iOS SDK.

SDK Method

(ApigeeClientResponse *)apiRequest: (NSString *)url operation:(NSString *)op data:(NSString *)opData

Properties

Parameter Description
url A fully-formed request url in the following format:
https://api.usergrid.com/<org>/<app>/<collection>/?ql=

Note that you must include an empty '?ql=' query string at the end of the URL

op The HTTP method - in this case, 'PUT'
opData A JSON-formatted string that contains the entity properties to be updated

Example Request/Response

Request:

-(NSString*)updateCollection {

	NSString *url = @"https://api.usergrid.com/your-org/your-app/items/?ql";
	NSString *op = @"PUT";
	NSString *opData = @"{\"availability\":\"in-stock\"}"; //we escape the quotes
	
	//we recommend you call ApigeeClient from your AppDelegate. 
	//for more information see the iOS SDK install guide: http://apigee.com/docs/app-services/content/installing-apigee-sdk-ios
	//create an instance of AppDelegate
	AppDelegate *appDelegate = (AppDelegate *)[[UIApplication sharedApplication] delegate];
	
	//call apiRequest to initiate the API call
	ApigeeClientResponse *response = [appDelegate.dataClient apiRequest: url operation: op data: opData];
	
	@try {
	    //success
	}
	@catch (NSException * e) {
	    //fail
	}

}
				

Response:

{
  "action" : "put",
  "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
  "params" : {
    "ql" : [ "" ]
  },
  "path" : "/items",
  "uri" : "http://api.usergrid.com/your-org/your-app/items",
  "entities" : [ {
    "uuid" : "31847b9a-1a62-11e3-be04-8d05e96f700d",
    "type" : "item",
    "name" : "milk",
    "price" : "3.25",
    "availability" : "in-stock"
    "created" : 1378849479113,
    "modified" : 1378849567301,
    "name" : "milk",
  }, {
    "uuid" : "3192ac6a-1a62-11e3-a24f-496ca1d42ce7",
    "type" : "item",
    "name" : "bread",
    "price" : "4.00",
    "availability" : "in-stock"
    "created" : 1378849479206,
    "modified" : 1378849567351,
    "name" : "bread",
  } ],
  "timestamp" : 1378849567280,
  "duration" : 207,
  "organization" : "your-org",
  "applicationName" : "your-app"
}

Updating all entities in a collection is not currently supported by the Android SDK.

This example uses the JavaScript (HTML5) SDK.

SDK Method

request(options, callback)

Parameters

Parameter Description
options

A JSON-formatted object containing the following properties:

  • endpoint: the UUID or name of the collection to be updated, appended by an empty query string in the format: <collection>/?ql=
  • method: the HTTP method for the request – in this case PUT
  • body: the body of the request that specifies the properties to be updated in JSON format
callback Callback function to handle the API response

Example Request/Response

Request:

//create the basic client object
var dataClient = new Apigee.Client({
	orgName:'your-org',
	appName:'your-app'
});

//options for the request
var options = {
	endpoint:"items/?ql=", //don't forget to append '/?ql='
	method:"PUT",
	body: {"availability":"in-stock"}
}

dataClient.request(options,function (error, result) {

	if (error) { 
	    // Error
	} else { 
		// Success
	}

});    
				

Response:

Object {action: "put", application: "f34f4222-a166-11e2-a7f7-02e81adcf3d0", params: Object, path: "/items", uri: "http://api.usergrid.com/your-org/your-app/items"…}
action: "put"
application: "f34f4222-a166-11e2-a7f7-02e81adcf3d0"
applicationName: "your-app"
duration: 92
entities: Array[2]
	0: Object
		availability: "in-stock"
		created: 1378852309294
		modified: 1378853303215
		name: "milk"
		price: "3.25"
		type: "item"
		uuid: "c86ffbf0-1a68-11e3-ab22-3713e5fcf9d2"
		__proto__: Object
	1: Object
		availability: "in-stock"
		created: 1378852309373
		modified: 1378853303256
		name: "bread"
		price: "4.00"
		type: "item"
		uuid: "c87be2da-1a68-11e3-80f4-975f1f8b1f86"
		__proto__: Object
	length: 2
	__proto__: Array[0]
organization: "your-org"
params: Object
path: "/items"
timestamp: 1378853303201
uri: "http://api.usergrid.com/your-org/your-app/items"
__proto__: Object
				

This example uses the RubyGem.

SDK Method

collection.update_query(properties, query_string)

Properties

Parameter Description
properties JSON-formatted string that contains the entity properties to be updated
query_string A query string that specifies the entities to be updated. Use an empty string ("") to update all entities.

Example Request/Response

Request:

#Create a client object
usergrid_api = 'https://api.usergrid.com'
organization = 'your-org'
application = 'your-app'

client = Usergrid::Application.new "#{usergrid_api}/#{organization}/#{application}"

begin
	collection = client['items'].collection
	collection.update_query({availability: 'in-stock'},"")
rescue
	#fail
end
				

Response:

{
  "action" : "put",
  "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
  "params" : {
    "ql" : [ "" ]
  },
  "path" : "/items",
  "uri" : "http://api.usergrid.com/your-org/your-app/items",
  "entities" : [ {
    "uuid" : "31847b9a-1a62-11e3-be04-8d05e96f700d",
    "type" : "item",
    "name" : "milk",
    "price" : "3.25",
    "availability" : "in-stock"
    "created" : 1378849479113,
    "modified" : 1378849567301,
    "name" : "milk",
  }, {
    "uuid" : "3192ac6a-1a62-11e3-a24f-496ca1d42ce7",
    "type" : "item",
    "name" : "bread",
    "price" : "4.00",
    "availability" : "in-stock"
    "created" : 1378849479206,
    "modified" : 1378849567351,
    "name" : "bread",
  } ],
  "timestamp" : 1378849567280,
  "duration" : 207,
  "organization" : "your-org",
  "applicationName" : "your-app"
}

The example assumes use of the Node.js module.

SDK Method

request(options,callback);

Parameters

Parameter Description
options

A JSON-formatted object containing the following properties:

  • endpoint: the UUID or name of the collection to be updated, appended by an empty query string in the format: <collection>/?ql=
  • method: the HTTP method for the request, in this case PUT
callback Callback function to handle the API response

Example Request/Response

Request:

//Create the client object
var dataClient = new Usergrid.client({
    orgName:'your-org',
    appName:'your-app'
});

//Specify the options for the request
var options = {
	endpoint:"items/?ql=", //don't forget to append '/?ql='
	method:"PUT",
	body: {"availability":"in-stock"}
}

dataClient.request(options,function (error,result) {

    if (error) { 
        //error
	} else { 
		//success
	}

});    			
				

Response:

{ action: 'put',
  application: 'f34f4222-a166-11e2-a7f7-02e81adcf3d0',
  params: { ql: [ '' ] },
  path: '/items',
  uri: 'http://api.usergrid.com/your-org/your-app/items',
  entities: 
   [ { uuid: 'c86ffbf0-1a68-11e3-ab22-3713e5fcf9d2',
       type: 'item',
       name: 'milk',
       created: 1378852309294,
       modified: 1378855073613,
       availability: 'in-stock' },
     { uuid: 'c87be2da-1a68-11e3-80f4-975f1f8b1f86',
       type: 'item',
       name: 'bread',
       created: 1378852309373,
       modified: 1378855073655,
       availability: 'in-stock' } ],
  timestamp: 1378855073595,
  duration: 106,
  organization: 'your-org',
  applicationName: 'your-app' }
				

 

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)