Homepage

Properties

Last edit: Nov 03, 2023

Properties are used to persist data in platformOS.

Defining a Property

Properties are defined in YML configuration files for Tables. You have to provide a name and a type. For example:

properties:
- name: name
  type: string
- name: enabled
  type: boolean
- name: age
  type: integer

The above configuration adds three properties: "name" of type string, "enabled" of type boolean, and "age" of type integer.

Property Types

Each Property is described with the type of data that is stored within the database.
Please note that when processing your Property in Liquid, types are automatically converted to those supported by Liquid Data Types.

The table below lists available data types for Property configuration, that are used to configure fields on the database:

Type Description Example
array Arrays hold lists of variables of any type. Learn more in Arrays [1, 2, 3]
boolean Booleans are used to represent true/false values. true
date Stores Date "2017-07-07"
datetime Stores DateTime with time zone. It is recommended to store date and time in one format, so if you provide it in different formats, platformOS will convert it to ISO 8601; that’s what GraphQL expects as well. Please note the to_time filter which is very powerful in terms of parsing time. You can display dates/times in any format you want using the localize filter. "2017-07-07 14:00:00 +0000"
float Real numbers 1.0
integer Whole numbers that can be positive, negative, or 0 1
upload Learn more in User Uploads
string A UTF-8 character sequence "Some String"

Grouping into records

You can group your Properties into Records.

Form

You can configure Properties settings in Form similarly to other parameters:

...
fields:
  properties:
    name:
      validation:
        presence: true
    age:
      validation:
        presence: true

{% form %}
  <label for="name">Name</label>
  <input value="{{ form.fields.properties.name.value }}" name="{{ form.fields.properties.name.name }}" id="name" type="text">
  {% if form.errors['properties.name'] %}
    <p>{{ form.errors['properties.name'] }}</p>
  {% endif %}
{% endform %}

For more information visit our Form Builder Reference and our Building a Contact Form with Records tutorial.

Fetching a Property with GraphQL depending on type

Properties depend on their parent objects and are accessible in the query after mapping the name of the Property with the query attribute name. You can do that with the family of property defined in (GraphQL PropertiesInterface)[/api-reference/graphql/propertiesinterface.html], for example:

query get_records {
  records(
    per_page: 20,
    filter: {
      table: { value: "employee" }
    }
  ) {
    results {
      name: property(name: "name")
      age: property_int(name: "age")
      enabled: property_boolean(name: "enabled")
    }
  }
}

Filtering Properties with GraphQL

You can filter GraphQL results based on object properties values. All options are defined in GraphQL PropertyFilterInput. Some examples:

value - matches the value of given property.

query get_all_johns {
  records(
    per_page: 20,
    filter: {
      properties: [{ name: "name", value: "John" }]
    }
  ) {
    results {
      first_name: property(name: "name")
    }
  }
}

not_value - does not match the value of given property.

query get_evrybody_except_johns {
  records(
    per_page: 20,
    filter: {
      properties: [{ name: "name", not_value: "John" }]
    }
  ) {
    results {
      first_name: property(name: "name")
    }
  }
}

value_int - matches the value of given property.

query get_all_records_with_age_14 {
  records(
    per_page: 20,
    filter: {
      properties: [{ name: "age", value_int: 14 }]
    }
  ) {
    results {
      first_name: property(name: "name")
      age: property(name: "age")
    }
  }
}

value_float - matches the value of given property.

query get_all_records_with_discount_twenty {
  records(
    per_page: 20,
    filter: {
      properties: [{ name: "discount", value_float: 0.2 }]
    }
  ) {
    results {
      first_name: property(name: "name")
      discount: property(name: "discount")
    }
  }
}

value_boolean - matches the value of given property.

query get_all_records_with_discount {
  records(
    per_page: 20,
    filter: {
      properties: [{ name: "discount", value_boolean: true }]
    }
  ) {
    results {
      first_name: property(name: "name")
    }
  }
}

value_in - matches any value of provided array.

query get_all_johns_and_annas {
  records(
    per_page: 20,
    filter: {
      properties: [{ name: "name", value_in: ["John", "Anna"] }]
    }
  ) {
    results {
      first_name: property(name: "name")
    }
  }
}

not_value_in - does not match any value of provided array.

query get_everyone_except_johns_and_annas {
  records(
    per_page: 20,
    filter: {
      properties: [{ name: "name", not_value_in: ["John", "Anna"] }]
    }
  ) {
    results {
      first_name: property(name: "name")
    }
  }
}

range - available options for range are: lt, lte, gt, gte:

query get_all_adults_below_60 {
  records(
    per_page: 20,
    filter: {
      properties: [{ name: "age", range: { gte: $adult_age_treshold, lt: 60 } }]
    }
  ) {
    results {
      first_name: property(name: "name")
    }
  }
}

range uses ISO 8601 date-time formats, for example:

{
  name: "last_time_active",
  range: {
    lte: "2019-10-02T08:13:00",
    gte: "2019-09-01T08:13:00"
  }
}

exists

query get_all_with_name {
  records(
    per_page: 20,
    filter: {
      properties: [{ name: "name", exists: true }]
    }
  ) {
    results {
      first_name: property(name: "name")
    }
  }
}

Please note that the above examples are only valid for Properties defined on Table. Please refer to the GraphQL schema in order to filter Properties defined on different parents than Tables.

Questions?

We are always happy to help with any questions you may have.

contact us