Defining Custom Entities

Custom entities are user-defined data structures for storing app data. Forge's storage API lets you query data stored in these structures using a wide array of query conditions. These query conditions make it possible to build advanced, complex queries to suit your app's operations.

Custom entities are keys with multiple typed or untyped attributes. You can define attributes with the following data types:

• string
• integer
• float
• boolean
• any

Custom entities are defined in your manifest.yml as part of the storage property. Each custom entity also includes an indexes section where you define your query's filter patterns (more on this later). The storage property is a child of app, and uses the following syntax:

1
2
app:
  id: "ari:cloud:ecosystem::app/406d303d-0393-4ec4-ad7c-1435be94583a"
[...]
  storage:
    entities:
      - name: <custom entity name>
        attributes:
          <attribute1>: 
            type: <type>
          <attribute2>: 
            type: <type>
          <attributeN>: 
            type: <type>
        indexes: 
          - <attributeN>
          - <attributeN>
          - name: <by-any-name>
            partition: 
              - <attribute1>
              - <attribute2>
            range: 
              - <attributeN>

Related information

After declaring custom entities for your structure data, you can start building complex queries for them. See Querying the Custom Entity Store for more details.

For information about storing data in custom entities, see Storing data in custom entities .

For a detailed tutorial on storing and querying structured data through custom entities, see Use custom entities to store structured data.

Limitations

Custom entities are subject to the following limitations:

Values

Stored entity values must adhere to the following limitations:

Entity and index deletion

Once you've deployed your app, any entities, attributes, or indexes included in your manifest can no longer be deleted. If you do, Forge will return an error. We are working on addressing this in a future update.

You can still add new attributes and indexes to an existing entity. Doing so will not count as an entity deletion.

Indexes

While the entities property assigns multiple attributes to each key, indexes sets which attributes to create indexes for. Attributes with indexes are optimized for your queries; as such, you should create indexes based on the query patterns you intend to use.

Index types

You can declare either a simple or named index.

A simple index specifies one attribute (which you can use to reference the index in your queries):

1
2
indexes:
  - <attribute>

A named index allows you to optimize for more complex query patterns. Named indexes use the following parameters:

name

range

partition

The range and partition parameters can be used together or alone; both accept all data types (except for any). If you use either or both, you must set a name.

The following snippet shows the basic syntax for a named index:

1
2
indexes:
  - name: <value>
    range: 
      - <attribute>
    partition: 
      - <attribute1>
      - <attribute2>
      - <attribute3>

Deploying apps with indexes

If your app uses indexes, the forge deploy command will send an indexing request to Forge's hosted storage service. This storage service will then create or update indexes as necessary while your app's code is deployed. The indexing process's duration scales with your data set's size, from a minimum of 5 minutes for small data sets.

The indexing process is independent of the rest of the deployment. As such, the forge deploy command will normally complete while the indexing process is still ongoing. Until the indexing process completes, you won't be able to install your app on any sites.

To check the status of the indexing process on an environment (namely, development or staging), run:

1
2
forge storage entities indexes list -e <environment>

The indexing process is complete once all indexes have an ACTIVE status.

Example entity

The following manifest.yml excerpt shows a custom entity named employee with several attributes and indexes:

1
2
app:
  id: "ari:cloud:ecosystem::app/406d303d-0393-4ec4-ad7c-1435be94583a"

  storage:
    entities:
      - name: employee
        attributes:
          surname: 
            type: string
          age: 
            type: integer
          employmentyear: 
            type: integer
          gender: 
            type: string
          nationality: 
            type: string
        indexes:
          - surname
          - employmentyear
          - name: by-age
            range: 
              - age
          - name: by-age-per-gender
            partition: 
              - gender
            range: 
              - age  

This entity also creates four indexes based on the following employee attributes:

• surname
• employmentyear
• age (further optimized for filtering according to different age ranges)
• age per gender (further optimized for filtering according to age ranges for each gender)

For examples of queries you can make against this example entity, see Example queries in the Complex query page.