TAGS

Apply subsequent annotations only when the endpoint has specific tags.

Overview

Tags are automatically assigned to endpoints by different routine sources (functions, procedures, tables, views). The for/tags annotation allows you to conditionally apply annotations based on these tags.

This is useful for:

• Applying different configurations based on routine volatility (volatile, stable, immutable)
• Customizing behavior for CRUD operations (select, insert, update, delete)
• Environment-specific settings when combined with custom tags

Keywords

for, tags, tag

Syntax

for <tag1> [tag2] [tag3] ...
tags <tag1> [tag2] [tag3] ...

Annotations following the for/tags line apply only when the endpoint has at least one of the specified tags.

Automatic Tags by Source

Function or Procedure Source

Tags are assigned based on routine volatility:

Tag	Description
volatile	Functions declared as VOLATILE
stable	Functions declared as STABLE
immutable	Functions declared as IMMUTABLE
other	Procedures and other routines

Table or View CRUD Source

Different CRUD operations receive different tags:

Operation	Tags
Select	select, read, get
Insert	insert, put, create
Insert On Conflict Do Nothing	insert, put, create, insert_on_conflict_do_nothing, on_conflict_do_nothing, on_conflict
Insert On Conflict Do Nothing Returning	insert, put, create, insert_on_conflict_do_nothing_returning, on_conflict_do_nothing, on_conflict, returning
Insert On Conflict Do Update	insert, put, create, insert_on_conflict_do_update, on_conflict, on_conflict_do_update
Insert On Conflict Do Update Returning	insert, put, create, insert_on_conflict_do_update_returning, on_conflict_do_update, on_conflict, returning
Update Returning	update, post, update_returning, returning
Delete	delete
Delete Returning	delete, delete_returning, returning

Examples

Volatility-Based Configuration

-- Apply caching only to immutable functions
comment on function calculate_hash(_data text) is
'HTTP GET
for immutable
cached';

CRUD-Specific Authorization

-- On a table, require authorization only for write operations
comment on table products is
'for select
allow_anonymous
for insert update delete
authorize admin';

Environment-Specific Authorization

comment on function sensitive_data() is
'HTTP GET
for production
authorize admin
for development
allow_anonymous';

Tag-Specific Paths

comment on function get_users() is
'HTTP GET
for v1
path /api/v1/users
for v2
path /api/v2/users';

Multiple Tags

-- Apply rate limiting to all volatile operations
comment on function api_call() is
'HTTP POST
for volatile insert update delete
rate_limiter_policy strict';

Behavior

• Annotations after for/tags apply until the next for/tags line or end of comment
• If an endpoint matches any of the specified tags, the annotations are applied
• Tags are case-insensitive
• Multiple for/tags blocks can be used in the same comment
• Custom tags can be defined in addition to automatic tags

Related

• OpenAPI configuration - Tags are used in OpenAPI grouping
• Comment Annotations Guide - How annotations work
• Configuration Guide - How configuration works

Related Annotations

• ENABLED - Enable for specific tags
• DISABLED - Disable for specific tags