Designing Fields, Queries and Links

A few decisions made when a table is created are hard to change later: the identifier, the field
names, which fields are queryable, and how records point at products or other entities. This page
explains how to make them well.

Model the query first

Before creating fields, write down how the data will be read:

Which values will merchants filter by in the admin?

Which values will the storefront filter or sort by?

Which pages should show the records — every page, or only the page of one product, brand,
category or collection?

The answers decide which fields are queryable, which are required, and which relationships
belong in entity links.

Spend the queryable budget deliberately

A table can have 10 queryable fields. Only queryable fields can be filtered, in the admin and on
the storefront.

Make a field queryable when someone will filter by it: a code, a city, a status flag, a category.

Leave long descriptions and notes non-queryable unless partial text matching on them is really
needed.

Decide when creating the table. A field made queryable later works, but older records become
filterable only once indexing catches up.

Switching queryable off frees one of the 10 slots for another field, but the field's index path,
and its storage and write cost, stay in place.

Filtering and sorting

Filters use the form field:operator:value. Several filters must all match.

Operator	Matches	Example
`eq`	Exactly equal. Case-sensitive for text.	`city:eq:Athens`
`neq`	Not equal.	`status:neq:archived`
`gt`, `gte`	Greater than, greater than or equal.	`price:gte:10`
`lt`, `lte`	Less than, less than or equal.	`published_on:lt:2026-01-01`
`contains`	Text fields only: contains the value, ignoring case. The value cannot be empty.	`headline:contains:run`

Values are read according to the field's type: true / false for Yes / No, a number for
Number.

contains is a plain substring match, not a wildcard or pattern. There is no in or like.

Dates are compared as text, so a date-only bound works on whole days:
published_on:gte:2026-01-01 together with published_on:lt:2026-02-01 returns January 2026.

Sorting orders by one field, ascending or descending. The field must be queryable and
required: queryable puts it in the index, and required guarantees every record has a value, so no
record drops out of a sorted list. If you want to sort by a field, make it both when you create the
table. Without a sort, the newest records come first.

Use links for relationships

An entity link is a type + id pair that ties a record to a platform entity. It extends products,
brands, categories and collections by reference, without changing them.

Link type	Picked up automatically by
`product`	The Noir Custom Table component on product pages.
`brand`	The component on brand pages.
`category`	The component on category pages.
`collection`	The component on collection pages.
Any other type	Stored and filterable, but only your own theme code uses it.

Use the entity's id as the platform shows it.

A record can link to several entities, and many records can link to the same entity.

Links are not checked: the platform does not verify that the entity exists, deleting a product does
not delete or update records linked to it, and there is no lookup from a product to its records
other than filtering the table by link.

Prefer a link over storing an entity id in a Text field. Only links can be filtered with
linkType / linkId, and only links make the storefront component's Filter by page entity
work.

Use links for relationships, fields for attributes. If a value identifies another platform
entity, it belongs in a link. If it describes this record, it belongs in a field.

Structuring tables

One table per concept. Avoid a generic "settings" table with a kind field. Separate tables
get their own fields, validation and queryable budget.

Keep records flat and small. A Text field can hold JSON, but it is stored as plain text: nothing
inside it is validated or filterable. If a list needs validating or filtering, give its items their
own table and link both tables to the same entity.

Choose stable names. Identifiers and field names cannot be renamed without migrating data. Name
them after the concept; the table Name carries the display label.

Keep one date format for every record.

No secrets or personal data. Every admin user with the Customization permission can read every
table, and publishing a table exposes all of its fields to anyone. If a table mixes public content
with internal notes, split it into two tables and publish only one.

Example: a store locator

A merchant with 40 shops wants a store-locator page, filterable by city, with pickup points marked.

Field	Type	Required	Queryable	Why
`code`	Text	✅	✅	The merchant's own shop code, used to look one shop up.
`name`	Text	✅		Display only. Required so it can be the component's Title field.
`city`	Text	✅	✅	The main filter, and sortable because it is also required.
`address`	Text	✅		Display only.
`phone`	Text			Display only.
`latitude`	Number			Map pin.
`longitude`	Number			Map pin.
`is_pickup_point`	Yes / No		✅	Shows only the pickup points.
`opening_hours`	Text			Free text.

Three of the ten queryable fields are used, leaving room to grow. If opening hours ever need to be
validated or filtered per day, move them to a second table with one record per shop and day, each
linked to its shop with a custom link type, for example type shop and the shop's code as the id.

Designing Fields, Queries and Links

Model the query first#

Spend the queryable budget deliberately#

Filtering and sorting#

Use links for relationships#