Skip to main content

Internal Attributes

The Entity constructor automatically adds internal attributes to your schemas:

If the schema contains a conflicting attribute, the constructor throws a reservedAttributeName error. To avoid this, DynamoDB-Toolbox lets you customize the name and savedAs property of the internal attributes.

tip

You can get familiar with the internal attributes by using the FormattedItem and SavedItem types (see Type Inference for more details):

🔎 Show code
import type { FormattedItem, SavedItem } from 'dynamodb-toolbox/entity'

const PokemonEntity = new Entity({
  name: 'Pokemon',
  schema: schema({
    pokemonClass: string().key().savedAs('pk'),
    pokemonId: string().key().savedAs('sk'),
    level: number()
  }),
  ...
})

// Pokemons in DynamoDB:
type SavedPokemon = SavedItem<typeof PokemonEntity>
// => {
//   pk: string,
//   sk: string,
//   level: number,
//   _et: "Pokemon",
//   _ct: string,
//   _md: string,
// }

// Fetched Pokemons: (`entity` attribute is hidden)
type FormattedPokemon = FormattedItem<typeof PokemonEntity>
// => {
//   pokemonClass: string,
//   pokemonId: string,
//   level: number,
//   created: string,
//   modified: string,
// }

entity​

A string attribute that tags your items with the Entity name.

This attribute is required for some features to work, like allowing for appropriate formatting when fetching multiple items of the same Table in a single operation (e.g. Queries or Scans). There are two consequences to that:

  • The name of an Entity cannot be updated once it has its first items (at least not without a data migration).
  • When migrating existing data to DynamoDB-Toolbox, you also have to add it to your items first.

By default, the attribute is hidden and named entity. This can be overridden via the entityAttributeHidden and entityAttributeName properties:

const PokemonEntity = new Entity({
  name: 'Pokemon',
  entityAttributeHidden: false,
  entityAttributeName: 'item',
  ...
})
info

The savedAs property must be specified at the Table level, via the entityAttributeSavedAs property.

Timestamp Attributes​

There are two timestamp attributes. Both of them are string attributes containing timestamps in ISO 8601 format:

  • created records when the item was created
  • modified records when the item was last modified

Timestamp attributes are optional. You can opt out by setting off the timestamps property:

const PokemonEntity = new Entity({
  ...
  // 👇 deactivates both timestamps
  timestamps: false
})

You can also manage them independently:

const PokemonEntity = new Entity({
  ...
  timestamps: {
    created: true,
    // 👇 deactivates `modified` attribute
    modified: false
  }
})

Customizing Timestamps:

Instead of true, you can provide an object to fine-tune each attribute. Available options:

name​

The name of the attribute:

const PokemonEntity = new Entity({
  ...
  timestamps: {
    ...
    modified: {
      // `modified` by default
      name: 'lastModified'
    }
  }
})

savedAs​

The savedAs property of the attribute:

const PokemonEntity = new Entity({
  ...
  timestamps: {
    ...
    modified: {
      // `_md` by default
      savedAs: '__lastMod__'
    }
  }
})

hidden​

Whether the attribute is hidden or not when formatting:

const PokemonEntity = new Entity({
  ...
  timestamps: {
    ...
    modified: {
      // `false` by default
      hidden: true
    }
  }
})