createTagRelationship
Attach an existing tag to a record (member, post, etc.) by creating a tag relationship. Ensure no duplicate link by checking uniqueness.
Instructions
Create a tag relationship - Create a new tagrelationship record. Writes live data.
Use when: attaching an existing tag to a record (member, post, etc.). The alternative for members is setting the member_tags field via updateUser with member_tag_action=1.
Required: tag_id, object_id, tag_type_id, added_by.
Pre-check before create (TRIPLE uniqueness): BD does NOT enforce uniqueness on the (tag_id, object_id, tag_type_id) triple. Attaching the same tag to the same object twice produces two rel_tag rows, which inflates tag counts on admin reports and can cause some widgets to render the same tag chip twice on the same record. Filter-find pattern (single-field server filter + client-side intersect - the server does not yet honor array-syntax multi-condition filters): call listTagRelationships property=tag_id property_value=<proposed tag_id> property_operator== to narrow to all rows for that tag, then CLIENT-SIDE filter to rows where object_id=<proposed object_id> AND tag_type_id=<proposed tag_type_id>. Zero results after client-side intersect = link free; >=1 = already attached. If the link already exists: skip the create (idempotent - the tag is already on the object). Never silently double-link.
Parameter interactions:
Attaches an existing tag to an existing record. Both sides must exist - use
listTagsand the target resource's list to discover IDs
See also: updateTagRelationship (modify existing).
tag_type_id + object_id - how to target the right record (from BD tag_types table):
The tag_type_id determines WHICH resource/table the object_id lives in. Discover mapping via listTagTypes - each tag type row has a table_relation field naming its target table. Example mapping:
tag_type_id | type_name | Target table (table_relation) | What object_id references |
1 | Users |
|
|
(other rows) | (other types) | e.g. | That table's primary key |
Process: call listTagTypes first to see the tag_type_id -> table_relation mapping on your site, then pick the appropriate tag_type_id and supply the matching record's PK as object_id. Widgets, menus, and forms all support tags via the same tag_type_id + object_id lookup pattern.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tag_id | Yes | Integer PK of the tag (`tags.id`) passed as a string per the underlying `varchar(500)` column. The schema column comment says "name of the tag" — that's legacy and misleading; BD stores the integer ID stringified. Discover via `listTags`. | |
| object_id | Yes | Primary key of the record being tagged. Which table it lives in depends on tag_type_id - look up via listTagTypes. For tag_type_id=1 (Users), object_id is a user_id from users_data. | |
| tag_type_id | Yes | Tag type classifier ID - determines which TABLE the `object_id` references. Call `listTagTypes` first to see the `tag_type_id` -> `table_relation` mapping. Example: `tag_type_id=1` usually means Users (`table_relation=users_data`), so `object_id` would be a `user_id`. Other tag types may target widgets, menus, forms. | |
| added_by | Yes |