<commit_before>---
order: 2
---
## Schema

Schemas are used to define DynamoDB table attributes and their constraints.

### Creating a new Schema

Schemas are created using `new Schema(attrDefObj, options)`.

The first argument (`attrDefObj`) is an object containing attribute definitions. Keys of this object correspond to attributes in the resulting DynamoDB table. The values of these keys define constraints on those attributes (as well as a few handy features...). See [Attribute Definitions](#attribute-definitions) for a more thorough description.

The second argument (`options`) defines options for the table that are beyond the scope of individual attributes. See [Schema Options](#schema-options) for more.

The following is an example of creating a new Schema:

```js
var Schema = dynamoose.Schema;

var dogSchema = new Schema({
  ownerId: {
    type: Number,
    validate: function(v) { return v > 0; },
    hashKey: true
  },
  name: {
    type: String,
    rangeKey: true,
    index: true // name: nameLocalIndex, ProjectionType: ALL
  },
  breed: {
    type: String,
    trim: true,
    required: true,
    index: {
      global: true,
      rangeKey: 'ownerId',
      name: 'BreedIndex',
      project: true, // ProjectionType: ALL
      throughput: 5 // read and write are both 5
    }
  },
  color: {
    lowercase: true,
    type: [String],
    default: ['Brown']
  },
  age: Number
},
{
  throughput: {read: 15, write: 5}
});
```

### Attribute Types

Attribute Types define the domain of a particular attribute. For example, a `name` might be set to `String` or `age` to `Number`.

The following table describes valid Attribute Types, and their translation to DynamoDB types:

| Attribute Type      | Resulting DynamoDB Type |
|:-------------------:|:-----------------------:|
| String              | 'S'                     |
| Number              | 'N'                     |
| Boolean<sup>*</sup> | 'S' or 'BOOL'           |
| Date                | 'N'                     |
| Object<sup>*</sup>  | 'S' or 'M'              |
| Array<sup>*</sup>   | 'S' or 'L'              |
| Buffer              | 'B'                     |
| [String]            | 'SS'                    |
| [Number]            | 'NS'                    |
| [Boolean]           | 'SS'                    |
| [Date]              | 'NS'                    |
| [Object]            | 'SS'                    |
| [Array]             | 'SS'                    |


<sup>*</sup> Use `useNativeBooleans` and `useDocumentTypes` to change DynamoDB type

### Attribute Definitions

Attribute definitions define constraints on a particular attribute specified in a Schema. Attribute definitions may be an object type (see [Attribute Types](#attribute-types)) or an object with the following options:

**type**: AttributeType _required_

Required for all attribute definitions. Defines the attribute type. See [Attribute Types](#attribute-types).

**hashKey**: boolean

Sets the attribute as the table's hash key. If this option isn't specified in a schema, then the first attribute is defined as the hash key.

**rangeKey**: boolean

Sets the attribute as the table's range key.

**required**: boolean

Sets the attribute as a 'required' attribute. Required attributes must not be saved as undefined or null, or an error will be thrown.

**index**: boolean &#124; object &#124; [objects]

Defines the attribute as a local or global secondary index. Index can either be true, an index definition object or and array of index definition objects. The array is used define multiple indexes for a single attribute. The index definition object can contain the following keys:

- _name: 'string'_ - Name of index (Default is `attribute.name + (global ? 'GlobalIndex' : 'LocalIndex')`).
- _global: boolean_ - Set the index to be a global secondary index.  Attribute will be the hash key for the Index.
- _rangeKey: 'string'_ - The range key for a global secondary index.
- _project: boolean &#124; ['string', ...]_ - Sets the attributes to be projected for the index.  `true` projects all attributes, `false` projects only the key attributes, and ['string', ...] projects the attributes listed. Default is `true`.
- _throughput: number &#124; {read: number, write: number}_ - Sets the throughput for the global secondary index.

**default**: function &#124; value

Applies a default to the attribute's value when saving, if the values is null or undefined.

If default is a function, the function is called with the current model instance, and the response is assigned to the attribute's value.

If it is a value, the value is simply assigned.

```js
function(model) {
    return model.name +'_'+ model.category;
}
```

**forceDefault: boolean**

(default: false) Will force the default value to always be applied to the attribute event if it already set. This is good for populating data that will be used as sort or secondary indexes.

**validate**: function, regular expression, or value

Validation required before for saving.

If validate is a function, the function is used to validate the attribute's value. The function must have the signature:

```js
function(value, model) {
  if(valid)
    return true;
  else
    return false;
}
```

If it is a RegExp, it is compared using `RegExp.test(value)`.

If it is a value, it is compared with `===`.

**set**: function

Adds a setter function that will be used to transform the value before writing to the DB.

**get**: function

Adds a getter function that will be used to transform the value returned from the DB, fired only if there is a value returned from the DB.

**toDynamo**: function

Adds a setter function that will directly set the value to the DB. This skips all type management and parsing normally provided by `options.set`.

**fromDynamo**: function

Adds a getter function that will be used to transform the value directly returned from the DB. This skips all type management and parsing normally provided by `options.get`.

**trim**: boolean

Trim whitespace from string when saving to DB.

**lowercase**: boolean

Convert to lowercase when saving to DB.

**uppercase**: boolean

Convert to uppercase when saving to DB.

### Options

**throughput**: number &#124; {read: number, write: number}

Sets the throughput of the DynamoDB table. The value can either be a number or an object with the keys `read` and `write` (for example: `{read: 5, write: 2}`). If it is a number, both read and write are configured to that number. If it is omitted, the read and write values will be set to 1.

```js
var schema = new Schema({...}, {
  throughput: 5
});
var schema = new Schema({...}, {
  throughput: {
    read: 5,
    write: 2
  }
});
```
<commit_msg>Making it more clear that throughput is only respected on table creation<commit_after>---
order: 2
---
## Schema

Schemas are used to define DynamoDB table attributes and their constraints.

### Creating a new Schema

Schemas are created using `new Schema(attrDefObj, options)`.

The first argument (`attrDefObj`) is an object containing attribute definitions. Keys of this object correspond to attributes in the resulting DynamoDB table. The values of these keys define constraints on those attributes (as well as a few handy features...). See [Attribute Definitions](#attribute-definitions) for a more thorough description.

The second argument (`options`) defines options for the table that are beyond the scope of individual attributes. See [Schema Options](#schema-options) for more.

The following is an example of creating a new Schema:

```js
var Schema = dynamoose.Schema;

var dogSchema = new Schema({
  ownerId: {
    type: Number,
    validate: function(v) { return v > 0; },
    hashKey: true
  },
  name: {
    type: String,
    rangeKey: true,
    index: true // name: nameLocalIndex, ProjectionType: ALL
  },
  breed: {
    type: String,
    trim: true,
    required: true,
    index: {
      global: true,
      rangeKey: 'ownerId',
      name: 'BreedIndex',
      project: true, // ProjectionType: ALL
      throughput: 5 // read and write are both 5
    }
  },
  color: {
    lowercase: true,
    type: [String],
    default: ['Brown']
  },
  age: Number
},
{
  throughput: {read: 15, write: 5}
});
```

### Attribute Types

Attribute Types define the domain of a particular attribute. For example, a `name` might be set to `String` or `age` to `Number`.

The following table describes valid Attribute Types, and their translation to DynamoDB types:

| Attribute Type      | Resulting DynamoDB Type |
|:-------------------:|:-----------------------:|
| String              | 'S'                     |
| Number              | 'N'                     |
| Boolean<sup>*</sup> | 'S' or 'BOOL'           |
| Date                | 'N'                     |
| Object<sup>*</sup>  | 'S' or 'M'              |
| Array<sup>*</sup>   | 'S' or 'L'              |
| Buffer              | 'B'                     |
| [String]            | 'SS'                    |
| [Number]            | 'NS'                    |
| [Boolean]           | 'SS'                    |
| [Date]              | 'NS'                    |
| [Object]            | 'SS'                    |
| [Array]             | 'SS'                    |


<sup>*</sup> Use `useNativeBooleans` and `useDocumentTypes` to change DynamoDB type

### Attribute Definitions

Attribute definitions define constraints on a particular attribute specified in a Schema. Attribute definitions may be an object type (see [Attribute Types](#attribute-types)) or an object with the following options:

**type**: AttributeType _required_

Required for all attribute definitions. Defines the attribute type. See [Attribute Types](#attribute-types).

**hashKey**: boolean

Sets the attribute as the table's hash key. If this option isn't specified in a schema, then the first attribute is defined as the hash key.

**rangeKey**: boolean

Sets the attribute as the table's range key.

**required**: boolean

Sets the attribute as a 'required' attribute. Required attributes must not be saved as undefined or null, or an error will be thrown.

**index**: boolean &#124; object &#124; [objects]

Defines the attribute as a local or global secondary index. Index can either be true, an index definition object or and array of index definition objects. The array is used define multiple indexes for a single attribute. The index definition object can contain the following keys:

- _name: 'string'_ - Name of index (Default is `attribute.name + (global ? 'GlobalIndex' : 'LocalIndex')`).
- _global: boolean_ - Set the index to be a global secondary index.  Attribute will be the hash key for the Index.
- _rangeKey: 'string'_ - The range key for a global secondary index.
- _project: boolean &#124; ['string', ...]_ - Sets the attributes to be projected for the index.  `true` projects all attributes, `false` projects only the key attributes, and ['string', ...] projects the attributes listed. Default is `true`.
- _throughput: number &#124; {read: number, write: number}_ - Sets the throughput for the global secondary index.

**default**: function &#124; value

Applies a default to the attribute's value when saving, if the values is null or undefined.

If default is a function, the function is called with the current model instance, and the response is assigned to the attribute's value.

If it is a value, the value is simply assigned.

```js
function(model) {
    return model.name +'_'+ model.category;
}
```

**forceDefault: boolean**

(default: false) Will force the default value to always be applied to the attribute event if it already set. This is good for populating data that will be used as sort or secondary indexes.

**validate**: function, regular expression, or value

Validation required before for saving.

If validate is a function, the function is used to validate the attribute's value. The function must have the signature:

```js
function(value, model) {
  if(valid)
    return true;
  else
    return false;
}
```

If it is a RegExp, it is compared using `RegExp.test(value)`.

If it is a value, it is compared with `===`.

**set**: function

Adds a setter function that will be used to transform the value before writing to the DB.

**get**: function

Adds a getter function that will be used to transform the value returned from the DB, fired only if there is a value returned from the DB.

**toDynamo**: function

Adds a setter function that will directly set the value to the DB. This skips all type management and parsing normally provided by `options.set`.

**fromDynamo**: function

Adds a getter function that will be used to transform the value directly returned from the DB. This skips all type management and parsing normally provided by `options.get`.

**trim**: boolean

Trim whitespace from string when saving to DB.

**lowercase**: boolean

Convert to lowercase when saving to DB.

**uppercase**: boolean

Convert to uppercase when saving to DB.

### Options

**throughput**: number &#124; {read: number, write: number}

Sets the throughput of the DynamoDB table on creation. The value can either be a number or an object with the keys `read` and `write` (for example: `{read: 5, write: 2}`). If it is a number, both read and write are configured to that number. If it is omitted, the read and write values will be set to 1. Throughput will only be respected on table creation, and will not update the throughput of an existing table.

```js
var schema = new Schema({...}, {
  throughput: 5
});
var schema = new Schema({...}, {
  throughput: {
    read: 5,
    write: 2
  }
});
```

{'fraction_non_alphanumeric': 0.10190988865127941, 'fraction_numerical': 0.0045719342231398865, 'mean_word_length': 3.0041334514319455, 'pattern_counts': {'":': 0, '<': 19, '<?xml version=': 0, '>': 21, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 8, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2316649', 'n_tokens_mistral': 3684, 'n_tokens_neox': 3524, 'n_words': 1775}