Developers · Data

Arrays

Last updated 1 November 2026

Store a list of text values in one property: define, write, read and filter array properties.

An array property stores a list of text values in one field, such as the tags on an article or the hobbies of a member. Use one when a record needs several values of the same kind and you do not need a separate table for them.

Warning

The schema says the array type will be deprecated in the future, because it can only store strings. For lists of other values, or values with their own fields, use a related table.

Define an array property

app/schema/member.yml

name: member
properties:
  - name: hobbies
    type: array

Sync the schema file and the table is updated within seconds.

Write an array

Set the whole list with value_array. To change one item, use array_append or array_remove in an update:

app/graphql/members/add_hobby.graphql

mutation add_hobby($id: ID!, $hobby: String!) {
  record_update(
    id: $id
    record: { properties: [{ name: "hobbies", array_append: $hobby }] }
  ) {
    id
  }
}

array_append and array_remove are atomic. They apply in the database before the rest of the update, so two people can change the list at once without losing a change. They skip validations and callbacks, and only work in update mutations.

Read and filter an array

app/graphql/members/by_hobby.graphql

query members_by_hobby($hobby: String!) {
  records(
    per_page: 20
    filter: {
      table: { value: "member" }
      properties: [{ name: "hobbies", array_contains: [$hobby] }]
    }
  ) {
    results { id hobbies: property_array(name: "hobbies") }
  }
}

Operator	Matches when
`array_contains`	The array holds all of the given values
`array_overlaps`	The array holds at least one of the given values
`value_array`	The array equals the given list, in the same order
`value_in`	Every element of the array is one of the given values

Note

The docs instance has no array properties, so these examples were not run. They follow the GraphQL schema and the Logic Engine schema rules.

Common mistakes

Reading an array with property. Use property_array to get a list back.
Using array_contains on a property that is not an array. The schema says it raises an error.
Writing [] after an input name in your own HTML. insites-cli audit reports it as a deprecated key.
Storing numbers in an array and expecting numeric filters. Elements are strings.