references/models-surveys.md
Surveys
Survey (system.surveys)
Surveys collect feedback from users through questions and forms.
Columns
Column | Type | Nullable | Description
--- | --- | --- | ---
id | UUID | NOT NULL | Survey id (UUID).
team_id | Integer | NOT NULL |
name | String | NOT NULL | Survey name.
type | String | NOT NULL | Survey delivery type, e.g. 'popover', 'api', 'widget'.
questions | JSON | NOT NULL | JSON array of the survey's questions.
appearance | JSON | NOT NULL | JSON styling/appearance configuration.
start_date | DateTime | NOT NULL | When the survey was launched; NULL if not started.
end_date | DateTime | NOT NULL | When the survey was stopped; NULL if still running.
created_by_id | Integer | NULL | User who created the survey.
created_at | DateTime | NOT NULL | When the survey was created.
Question Types
[
{
"id": "uuid",
"type": "open",
"question": "How can we improve?",
"optional": false,
"buttonText": "Submit"
},
{
"id": "uuid",
"type": "rating",
"question": "How would you rate us?",
"display": "number",
"scale": 10,
"lowerBoundLabel": "Not likely",
"upperBoundLabel": "Very likely"
},
{
"id": "uuid",
"type": "single_choice",
"question": "Which feature do you use most?",
"choices": ["Feature A", "Feature B", "Feature C"]
}
]
Key Relationships
- Feature Flags: Multiple flag relationships via
system.feature_flags
Important Notes
- Survey name must be unique per team
- Internal flags (
targeting_flag,internal_targeting_flag,internal_response_sampling_flag) are auto-managed linked_flagis user-managed and optional
SurveyResponseArchive (system.survey_response_archives)
Survey responses are stored as events, so archiving one is recorded in Postgres instead. One row per archived (hidden) response.
Columns
Column | Type | Nullable | Description
--- | --- | --- | ---
id | UUID | NOT NULL | Archive record UUID.
team_id | Integer | NOT NULL |
survey_id | UUID | NOT NULL | Survey the archived response belongs to; joins to surveys.id.
response_uuid | UUID | NOT NULL | UUID of the event holding the response; joins to events.uuid.
archived_at | DateTime | NOT NULL | When the response was archived.
Key Relationships
- Archived responses:
system.survey_response_archives.survey_id->system.surveys.id
Important Notes
- To exclude archived responses from a survey's results, anti-join the survey events against this table on
events.uuid = survey_response_archives.response_uuid (team_id, response_uuid)is unique