Merge 5956efe into 87608f7

docs/api/Condition.md

@@ -47,7 +47,7 @@ new dynamoose.Condition().where("id").eq(1).and().where("name").eq("Bob");
 new dynamoose.Condition().where("id").eq(1).where("name").eq("Bob");
 ```
 
-## condition.and()
+## condition.or()
 
 This function specifies an `OR` join between two conditions, as opposed to the default `AND`. The condition will return `true` if either condition is met.
 

docs/api/Document.md

@@ -2,6 +2,8 @@
 
 A document represents an item for a given model in DynamoDB. This item can created locally (meaning it's not yet saved in DynamoDB), or created from an item already stored in DynamoDB (ex. `Model.get`).
 
+_Info: An item is similar to a row in a relational database or a document in MongoDB._
+
 ## new Model(object)
 
 In order to create a new document you just pass in your object into an instance of your model.

docs/api/Model.md

@@ -1,26 +1,21 @@
 # Model
 
-The Model object represents one DynamoDB table. It takes in both a name and a schema and has methods to retrieve, and save items in the database.
+The Model object represents a table in DynamoDB. It takes in both a name and a schema and has methods to retrieve, and save items in the database.
 
 ## new dynamoose.Model(name, schema[, config])
 
 This method is the basic entry point for creating a model in Dynamoose. When you call this method a new model is created, and it returns a Document initializer that you can use to create instances of the given model.
 
-The `schema` parameter can either be an object OR a Schema instance. If you pass in an object for the `schema` parameter it will create a Schema instance for you automatically.
+The `schema` parameter can either be an object OR a [Schema](Schema.md) instance. If you pass in an object for the `schema` parameter it will create a Schema instance for you automatically.
 
 ```js
-const dynamoose = require("dynamoose");
-
 const Cat = new dynamoose.Model("Cat", {"name": String});
-```
-
-```js
-const dynamoose = require("dynamoose");
-
+const Cat = new dynamoose.Model("Cat", {"name": String}, {"create": false});
 const Cat = new dynamoose.Model("Cat", new dynamoose.Schema({"name": String}));
+const Cat = new dynamoose.Model("Cat", new dynamoose.Schema({"name": String}), {"create": false});
 ```
 
-The config parameter is an object used to customize settings for the model.
+The `config` parameter is an object used to customize settings for the model.
 
 | Name | Description | Type | Default |
 |------|-------------|------|---------|
@@ -124,7 +119,7 @@ async function printTableRequest() {
 }
 ```
 
-## Model.get(hashKey[, settings][, callback])
+## Model.get(key[, settings][, callback])
 
 You can use Model.get to retrieve a document from DynamoDB. This method uses the `getItem` DynamoDB API call to retrieve the object.
 
@@ -173,7 +168,7 @@ User.get(1, {"return": "request"}, (error, request) => {
 });
 ```
 
-In the event you have a rangeKey for your model, you can pass in an object for the `hashKey` parameter.
+In the event you have a rangeKey for your model, you can pass in an object for the `key` parameter which includes the hashKey & rangeKey.
 
 ```js
 const User = new dynamoose.Model("User", {"id": Number, "name": {"type": String, "rangeKey": true}});
@@ -278,7 +273,7 @@ User.batchGet([1, 2], {"return": "request"}, (error, request) => {
 });
 ```
 
-In the event you have a rangeKey for your model, you can pass in an object for the `hashKey` parameter.
+In the event you have a rangeKey for your model, you can pass in an object for the `key` parameter which includes the rangeKey & the hashKey.
 
 ```js
 const User = new dynamoose.Model("User", {"id": Number, "name": {"type": String, "rangeKey": true}});
@@ -399,9 +394,11 @@ await User.batchPut([
 });
 ```
 
-## Model.update(keyObj[, updateObj[, settings]],[ callback])
+## Model.update(key[, updateObj[, settings]],[ callback])
+
+This function lets you update an existing item in the database. You can either pass in one object combining both the hashKey (partition key) you wish to update along with the update object, or keep them separate by passing in two objects.
 
-This function lets you update an existing document in the database. You can either pass in one object combining both the hashKey you wish to update along with the update object, or keep them separate by passing in two objects.
+`key` can be a string representing the hashKey or an object containing the hashKey & rangeKey.
 
 ```js
 await User.update({"id": 1, "name": "Bob"}); // This code will set `name` to Bob for the user where `id` = 1
@@ -435,7 +432,7 @@ User.update({"id": 1}, {"name": "Bob"}, (error, user) => {
 ```
 
 ```js
-// The following code below will only update the item if the `active` property on the existing document is set to true
+// The following code below will only update the document if the `active` property on the existing document is set to true
 
 const condition = new dynamoose.Condition().where("active").eq(true);
 
@@ -481,9 +478,11 @@ await User.update({"id": 1}, {"name": "Bob", "$ADD": {"age": 1}});
 
 The `validate` Schema attribute property will only be run on `$SET` values. This is due to the fact that Dynamoose is unaware of what the existing value is in the database for `$ADD` properties.
 
-## Model.delete(hashKey[, settings][, callback])
+## Model.delete(key[, settings][, callback])
 
-You can use Model.delete to delete a document from DynamoDB. This method uses the `deleteItem` DynamoDB API call to delete the object.
+You can use Model.delete to delete a item from DynamoDB. This method uses the `deleteItem` DynamoDB API call to delete the object.
+
+`key` can be a string representing the hashKey or an object containing the hashKey & rangeKey.
 
 This method returns a promise that will resolve when the operation is complete, this promise will reject upon failure. You can also pass in a function into the `callback` parameter to have it be used in a callback format as opposed to a promise format. In the event the operation was successful, noting will be returned to you. Otherwise an error will be thrown.
 
@@ -530,7 +529,7 @@ User.delete(1, {"return": "request"}, (error, request) => {
 });
 ```
 
-In the event you have a rangeKey for your model, you can pass in an object for the `hashKey` parameter.
+In the event you have a rangeKey for your model, you can pass in an object for the `key` parameter which includes the rangeKey & the hashKey.
 
 ```js
 const User = new dynamoose.Model("User", {"id": Number, "name": {"type": String, "rangeKey": true}});
@@ -576,7 +575,9 @@ User.delete({"id": 1}, (error) => {
 
 ## Model.batchDelete(keys[, settings][, callback])
 
-You can use Model.batchDelete to delete documents from DynamoDB. This method uses the `batchWriteItem` DynamoDB API call to delete the objects.
+You can use Model.batchDelete to delete items from DynamoDB. This method uses the `batchWriteItem` DynamoDB API call to delete the objects.
+
+`keys` can be an array of strings representing the hashKey and/or an array of objects containing the hashKey AND rangeKey.
 
 This method returns a promise that will resolve when the operation is complete, this promise will reject upon failure. You can also pass in a function into the `callback` parameter to have it be used in a callback format as opposed to a promise format. In the event the operation was successful, an object with the `unprocessedItems` will be returned to you. Otherwise an error will be thrown.
 
@@ -644,7 +645,7 @@ User.batchDelete([1, 2], {"return": "request"}, (error, request) => {
 });
 ```
 
-In the event you have a rangeKey for your model, you can pass in an object for the `hashKey` parameter.
+In the event you have a rangeKey for your model, you can pass in an object for the `key` parameter which includes the rangeKey & the hashKey.
 
 ```js
 const User = new dynamoose.Model("User", {"id": Number, "name": {"type": String, "rangeKey": true}});

docs/api/Query.md

@@ -4,15 +4,17 @@ Dynamoose provides the ability to query a model by using the `Model.query` funct
 
 ## Model.query([filter])
 
-This is the basic entry point to construct a query request. The filter property is optional and can either be an object or a string representing the key you which to first filter on. In the event you don't pass in any parameters and don't call any other methods on the query object it will query with no filters or options.
+This is the basic entry point to construct a query request. It requires to set at least the hashKey of the item(s). The filter property is optional and can either be an object or a string representing the key you which to first filter on. In the event you don't pass in any parameters and don't call any other methods on the query object it will query with no filters or options.
 
 ```js
-Cat.query("breed").contains("Terrier").exec() // will query all items and filter all items where the key `breed` contains `Terrier`
-Cat.query({"breed": {"contains": "Terrier"}}).exec() // will query all items and filter all items where the key `breed` contains `Terrier`
+Cat.query("breed").contains("Terrier").exec() // will query all items where the hashKey `breed` contains `Terrier`
+Cat.query({"breed": {"contains": "Terrier"}}).exec() // will query all items where the hashKey `breed` contains `Terrier`
 ```
 
 If you pass an object into `Model.query` the object for each key should contain the comparison type. For example, in the last example above, `contains` was our comparison type. This comparison type must match one of the comparison type functions listed on this page.
 
+Please note: `Model.query()` combines both the `KeyConditionExpression` and the `FilterExpression` from DynamoDB. If you query for an attribute that you defined as your hashKey or rangeKey DynamoDB will use `KeyConditionExpression`. This could be the most performant and cost efficient way to query for. If querying for attributes that are not defined as your hashKey or rangeKey DynamoDB might select more items at first and then filter the result which could have a bad impact on performance and costs.    
+
 ## Conditionals
 
 On top of all of the methods listed below, every `Query` instance has all of the methods that a `Condition` instance has. This means you can use methods like `where`, `filter`, `eq`, `lt` and more.
@@ -112,7 +114,7 @@ Cat.query("name").eq("Will").using("name-index"); // Run the query on the `name-
 
 ## query.all([delay[, max]])
 
-Unlike most other query functions that directly change the DynamoDB query request, this function is purely internal and unique to Dynamoose. This function sends continuous query requests upon receiving the response so long as the `lastKey` property exists on the response. This can be useful if you wish to get all the items from the table and don't want to worry about checking the `lastKey` property and sending a new query request yourself.
+If a query result is more than the limit of your DynamoDB table, DynamoDB paginates the results so you would have to send multiple requests. This function sends continuous query requests until all items have been received (as long as the `lastKey` property exists on the response). This can be useful if you wish to get all the items from the table and don't want to worry about checking the `lastKey` property and sending a new query request yourself.
 
 Two parameters can be specified on this setting:
 

docs/api/Scan.md

@@ -1,6 +1,8 @@
 # Scan
 
-Dynamoose provides the ability to scan a model by using the `Model.scan` function. This function acts as a builder to construct your scan with the appropriate settings before executing it (`scan.exec`).
+Dynamoose provides the ability to scan a table (model) by using the `Model.scan` function. This function acts as a builder to construct your scan with the appropriate settings before executing it (`scan.exec`).
+
+Scan operations run on every document in your table or index. This means that all filtering is done after the documents are read, and therefore is not the most performant method. Due to that, if possible, it is highly encouraged to use [`Model.query`](Query.md) as opposed to `Model.scan`.
 
 ## Model.scan([filter])
 
@@ -123,7 +125,7 @@ Cat.scan().using("name-index"); // Run the scan on the `name-index` index
 
 ## scan.all([delay[, max]])
 
-Unlike most other scan functions that directly change the DynamoDB scan request, this function is purely internal and unique to Dynamoose. This function sends continuous scan requests upon receiving the response so long as the `lastKey` property exists on the response. This can be useful if you wish to get all the items from the table and don't want to worry about checking the `lastKey` property and sending a new scan request yourself.
+If a query result is more than the limit of your DynamoDB table (before filtering!), DynamoDB paginates the results so you would have to send multiple requests. This function sends continuous scan requests until all items have been received (as long as the `lastKey` property exists on the response). This can be useful if you wish to get all the items from the table and don't want to worry about checking the `lastKey` property and sending a new scan request yourself.
 
 Two parameters can be specified on this setting:
 

docs/api/Schema.md

@@ -322,7 +322,7 @@ Your index object can contain the following properties:
 | Name | Type | Default | Notes |
 |---|---|---|---|
 | name | string | `${attribute}${global ? "GlobalIndex" : "LocalIndex"}` | Name of index |
-| global | boolean | false | If the index should be a global secondary index or not. Attribute will be the hash key for the index. |
+| global | boolean | false | If the index should be a global secondary index or not. Attribute will be the hashKey for the index. |
 | rangeKey | string | undefined | The range key attribute name for a global secondary index. |
 | project | boolean \| [string] | true | Sets the attributes to be projected for the index. `true` projects all attributes, `false` projects only the key attributes, and an array of strings projects the attributes listed. |
 | throughput | number \| {read: number, write: number} | undefined | Sets the throughput for the global secondary index. |
@@ -332,24 +332,33 @@ If you set `index` to `true`, it will create an index with all of the default se
 
 ```js
 {
+    "id" : {
+      "hashKey": true,
+      "type": String,
+    },
 	"email": {
 		"type": String,
 		"index": {
-			"name": "emailIndex",
-			"global": true
-		} // creates a global index with the name `emailIndex`
+          "name": "emailIndex",
+          "global": true
+        } // creates a global secondary index with the name `emailIndex` and hashKey `email`
 	}
 }
 ```
 
 ```js
 {
+    "id" : {
+      "hashKey": true,
+      "type": String,
+      "index": {
+        "name": "emailIndex",
+        "rangeKey": "email",
+        "throughput": {"read": 5, "write": 10}
+      } // creates a local secondary index with the name `emailIndex`, hashKey `id`, rangeKey `email`
+    },
 	"email": {
-		"type": String,
-		"index": {
-			"name": "emailIndex",
-			"throughput": {"read": 5, "write": 10}
-		} // creates a global index with the name `emailIndex`
+		"type": String
 	}
 }
 ```
@@ -358,6 +367,8 @@ If you set `index` to `true`, it will create an index with all of the default se
 
 You can set this to true to overwrite what the `hashKey` for the Model will be. By default the `hashKey` will be the first key in the Schema object.
 
+`hashKey` is commonly called a `partition key` in the AWS documentation.
+
 ```js
 {
 	"id": String,
@@ -372,6 +383,8 @@ You can set this to true to overwrite what the `hashKey` for the Model will be.
 
 You can set this to true to overwrite what the `rangeKey` for the Model will be. By default the `rangeKey` won't exist.
 
+`rangeKey` is commonly called a `sort key` in the AWS documentation.
+
 ```js
 {
 	"id": String,