komp_ac/common/proto/analytics.proto

syntax = "proto3";

package komp_ac.analytics;

import "table_definition.proto";

import "google/protobuf/struct.proto";

// Runs read-only analytical SQL over runtime-defined profile tables.
// Public SQL uses table and column aliases; physical ordinal column names are
// resolved inside the server and are never exposed by this API.
service AnalyticsService {
  // Lists the alias-visible analytical tables for one profile.
  rpc GetAnalyticsCatalog(GetAnalyticsCatalogRequest) returns (GetAnalyticsCatalogResponse);

  // Executes one read-only SELECT query and streams typed result batches.
  rpc ExecuteAnalyticsQuery(ExecuteAnalyticsQueryRequest) returns (stream AnalyticsResultBatch);
}

message GetAnalyticsCatalogRequest {
  // Required PostgreSQL profile/schema name.
  string profile_name = 1;
}

message GetAnalyticsCatalogResponse {
  string profile_name = 1;
  repeated AnalyticsTable tables = 2;
}

message AnalyticsTable {
  int64 table_definition_id = 1;
  string name = 2;
  repeated AnalyticsCatalogColumn columns = 3;
  repeated AnalyticsTableLink links = 4;
}

message AnalyticsCatalogColumn {
  // Current public alias. Physical ordinal names are intentionally omitted.
  string name = 1;
  string field_type = 2;
  bool is_system = 3;
  komp_ac.table_definition.MoneyRounding rounding = 4;
  // Canonical ISO-4217 code for MONEY; empty for every other type.
  string currency = 5;
}

message AnalyticsTableLink {
  // Public foreign-key column on the source table, e.g. department_id.
  string source_column = 1;
  string linked_table = 2;
  bool required = 3;
}

message ExecuteAnalyticsQueryRequest {
  // Required profile whose tables form the query's complete visible catalog.
  string profile_name = 1;

  // Exactly one read-only SELECT query. Table and column names are public aliases.
  string sql = 2;

  // Result cap. Zero uses the server default; the server maximum still applies.
  uint32 max_rows = 3;
}

message AnalyticsResultColumn {
  string name = 1;
  string data_type = 2;
}

message AnalyticsValue {
  oneof kind {
    google.protobuf.NullValue null_value = 1;
    bool bool_value = 2;
    int64 int64_value = 3;
    uint64 uint64_value = 4;
    double double_value = 5;
    string string_value = 6;
    bytes bytes_value = 7;
  }
}

message AnalyticsResultRow {
  repeated AnalyticsValue values = 1;
}

message AnalyticsResultBatch {
  // Present on the first batch and omitted from later data batches.
  repeated AnalyticsResultColumn columns = 1;
  repeated AnalyticsResultRow rows = 2;

  // The final message contains no rows and carries completion metadata.
  bool is_final = 3;
  bool truncated = 4;
  uint64 row_count = 5;
  uint64 elapsed_ms = 6;
}

service ReportingService {
  rpc ListAssets(ListReportAssetsRequest) returns (ListReportAssetsResponse);
  rpc GetAsset(GetReportAssetRequest) returns (ReportAsset);
  rpc SaveDraft(SaveReportDraftRequest) returns (ReportAsset);
  rpc Validate(ValidateReportRequest) returns (ReportAsset);
  rpc Publish(PublishReportRequest) returns (ReportAsset);
  rpc ListVersions(ReportAssetRef) returns (ListReportVersionsResponse);
  rpc RestoreDraft(RestoreReportDraftRequest) returns (ReportAsset);
  rpc SetArchived(SetReportArchivedRequest) returns (ReportAsset);
  rpc ExecuteDataset(ExecuteReportDatasetRequest) returns (stream AnalyticsResultBatch);
  rpc GetPersonalViews(ReportAssetRef) returns (GetReportPersonalViewsResponse);
  rpc SavePersonalView(SaveReportPersonalViewRequest) returns (ReportPersonalView);
  rpc DeletePersonalView(DeleteReportPersonalViewRequest) returns (ReportMutationResult);
}

enum ReportAssetKind {
  REPORT_ASSET_KIND_UNSPECIFIED = 0;
  REPORT_ASSET_KIND_DATASET = 1;
  REPORT_ASSET_KIND_DASHBOARD = 2;
}

enum ReportReadMode {
  REPORT_READ_MODE_UNSPECIFIED = 0;
  REPORT_READ_MODE_PUBLISHED = 1;
  REPORT_READ_MODE_DRAFT = 2;
  REPORT_READ_MODE_VERSION = 3;
}

enum ReportDataType {
  REPORT_DATA_TYPE_UNSPECIFIED = 0;
  REPORT_DATA_TYPE_TEXT = 1;
  REPORT_DATA_TYPE_INTEGER = 2;
  REPORT_DATA_TYPE_DECIMAL = 3;
  REPORT_DATA_TYPE_DATE = 4;
  REPORT_DATA_TYPE_TIMESTAMP = 5;
  REPORT_DATA_TYPE_BOOLEAN = 6;
}

enum ReportFilterControl {
  REPORT_FILTER_CONTROL_UNSPECIFIED = 0;
  REPORT_FILTER_CONTROL_TEXT = 1;
  REPORT_FILTER_CONTROL_NUMBER = 2;
  REPORT_FILTER_CONTROL_DATE = 3;
  REPORT_FILTER_CONTROL_TIMESTAMP = 4;
  REPORT_FILTER_CONTROL_SELECT = 5;
  REPORT_FILTER_CONTROL_MULTISELECT = 6;
  REPORT_FILTER_CONTROL_CHECKBOX = 7;
}

enum ReportDefaultKind {
  REPORT_DEFAULT_KIND_UNSPECIFIED = 0;
  REPORT_DEFAULT_KIND_LITERAL = 1;
  REPORT_DEFAULT_KIND_TODAY = 2;
  REPORT_DEFAULT_KIND_MONTH_START = 3;
  REPORT_DEFAULT_KIND_YEAR_START = 4;
}

enum ReportNumberFormat {
  REPORT_NUMBER_FORMAT_UNSPECIFIED = 0;
  REPORT_NUMBER_FORMAT_NUMBER = 1;
  REPORT_NUMBER_FORMAT_CURRENCY = 2;
  REPORT_NUMBER_FORMAT_PERCENT = 3;
  REPORT_NUMBER_FORMAT_COMPACT = 4;
}

enum ReportPanelKind {
  REPORT_PANEL_KIND_UNSPECIFIED = 0;
  REPORT_PANEL_KIND_BAR = 1;
  REPORT_PANEL_KIND_LINE = 2;
  REPORT_PANEL_KIND_AREA = 3;
  REPORT_PANEL_KIND_PIE = 4;
  REPORT_PANEL_KIND_DONUT = 5;
  REPORT_PANEL_KIND_SCATTER = 6;
  REPORT_PANEL_KIND_HEATMAP = 7;
  REPORT_PANEL_KIND_TREEMAP = 8;
  REPORT_PANEL_KIND_FUNNEL = 9;
  REPORT_PANEL_KIND_GAUGE = 10;
  REPORT_PANEL_KIND_WATERFALL = 11;
  REPORT_PANEL_KIND_TABLE = 12;
  REPORT_PANEL_KIND_KPI = 13;
}

enum ReportOrientation {
  REPORT_ORIENTATION_UNSPECIFIED = 0;
  REPORT_ORIENTATION_VERTICAL = 1;
  REPORT_ORIENTATION_HORIZONTAL = 2;
}

enum ReportSortOrder {
  REPORT_SORT_ORDER_UNSPECIFIED = 0;
  REPORT_SORT_ORDER_SOURCE = 1;
  REPORT_SORT_ORDER_ASCENDING = 2;
  REPORT_SORT_ORDER_DESCENDING = 3;
}

enum ReportNullPolicy {
  REPORT_NULL_POLICY_UNSPECIFIED = 0;
  REPORT_NULL_POLICY_GAP = 1;
  REPORT_NULL_POLICY_ZERO = 2;
}

enum ReportCapability {
  REPORT_CAPABILITY_UNSPECIFIED = 0;
  REPORT_CAPABILITY_VIEW = 1;
  REPORT_CAPABILITY_FILTER = 2;
  REPORT_CAPABILITY_DRILL = 3;
  REPORT_CAPABILITY_EXPORT = 4;
  REPORT_CAPABILITY_CUSTOMIZE = 5;
}

enum ReportExecutionPurpose {
  REPORT_EXECUTION_PURPOSE_UNSPECIFIED = 0;
  REPORT_EXECUTION_PURPOSE_VIEW = 1;
  REPORT_EXECUTION_PURPOSE_PREVIEW = 2;
  REPORT_EXECUTION_PURPOSE_EXPORT = 3;
  REPORT_EXECUTION_PURPOSE_DRILL = 4;
}

message ReportScalar {
  oneof value {
    google.protobuf.NullValue null_value = 1;
    string text = 2;
    string integer = 3;
    string decimal = 4;
    string date = 5;
    string timestamp = 6;
    bool boolean = 7;
  }
}

message ReportParameterChoice {
  string label = 1;
  ReportScalar value = 2;
}

message ReportParameterLookup {
  string dataset_id = 1;
  string value_field = 2;
  string label_field = 3;
}

message ReportParameter {
  string key = 1;
  string label = 2;
  ReportDataType data_type = 3;
  ReportFilterControl control = 4;
  bool required = 5;
  bool multiple = 6;
  repeated ReportScalar default_values = 7;
  ReportDefaultKind default_kind = 8;
  repeated ReportParameterChoice choices = 9;
  ReportParameterLookup lookup = 10;
}

message ReportParameterBinding {
  string key = 1;
  repeated ReportScalar values = 2;
}

message ReportDatasetColumn {
  string key = 1;
  string label = 2;
  ReportDataType data_type = 3;
  ReportNumberFormat number_format = 4;
  string currency = 5;
  string currency_field = 6;
  optional uint32 fraction_digits = 7;
}

message ReportDatasetDefinition {
  string title = 1;
  string description = 2;
  // Parameters use named DataFusion placeholders, for example CAST($from AS DATE).
  string sql = 3;
  repeated ReportParameter parameters = 4;
  repeated ReportDatasetColumn columns = 5;
  uint32 max_rows = 6;
}

message ReportFilterTarget {
  string dataset_id = 1;
  string parameter_key = 2;
}

message ReportDashboardFilter {
  ReportParameter parameter = 1;
  repeated ReportFilterTarget targets = 2;
  bool primary = 3;
}

enum ReportPeriodBoundary {
  REPORT_PERIOD_BOUNDARY_UNSPECIFIED = 0;
  REPORT_PERIOD_BOUNDARY_INCLUSIVE = 1;
  REPORT_PERIOD_BOUNDARY_EXCLUSIVE = 2;
}

message ReportDateRange {
  string start_filter = 1;
  string end_filter = 2;
  ReportPeriodBoundary end_boundary = 3;
}

message ReportPeriod {
  string date_basis = 1;
  oneof selection {
    ReportDateRange date_range = 2;
    string accounting_period_filter = 3;
    string as_of_filter = 4;
  }
}

message ReportActionBinding {
  string filter_key = 1;
  string column_key = 2;
}

message ReportFilterAction {
  repeated ReportActionBinding bindings = 1;
}

message ReportRecordAction {
  string table_name = 1;
  string id_field = 2;
}

message ReportDashboardAction {
  string dashboard_id = 1;
  repeated ReportActionBinding bindings = 2;
}

message ReportPanelAction {
  string label = 1;
  oneof target {
    ReportFilterAction filter = 2;
    ReportRecordAction record = 3;
    ReportDashboardAction dashboard = 4;
  }
}

message ReportPanel {
  string id = 1;
  string title = 2;
  string description = 3;
  string dataset_id = 4;
  ReportPanelKind kind = 5;
  string x_field = 6;
  repeated string y_fields = 7;
  string series_field = 8;
  string size_field = 9;
  repeated string table_fields = 10;
  ReportOrientation orientation = 11;
  bool stacked = 12;
  bool show_legend = 13;
  bool show_labels = 14;
  uint32 width = 15;
  uint32 height = 16;
  repeated string colors = 17;
  ReportSortOrder sort_order = 18;
  string sort_field = 19;
  ReportNullPolicy null_policy = 20;
  optional double axis_min = 21;
  optional double axis_max = 22;
  repeated ReportPanelAction actions = 23;
}

message ReportGrant {
  oneof subject {
    string role = 1;
    string user_id = 2;
  }
  repeated ReportCapability capabilities = 3;
}

message ReportDashboardDefinition {
  string title = 1;
  string description = 2;
  repeated ReportDashboardFilter filters = 3;
  repeated ReportPanel panels = 4;
  repeated ReportGrant grants = 5;
  uint32 refresh_seconds = 6;
  repeated ReportDatasetVersionRef dataset_versions = 7;
  ReportPeriod period = 8;
  // Queries owned by this report; keys are used by panels and filter targets.
  repeated ReportQuery queries = 9;
}

message ReportQuery {
  string key = 1;
  ReportDatasetDefinition definition = 2;
}

message ReportDatasetVersionRef {
  string dataset_id = 1;
  // Zero selects the latest published dataset when the dashboard is published.
  uint64 version = 2;
}

message ReportDefinition {
  uint32 schema_version = 1;
  oneof content {
    ReportDatasetDefinition dataset = 2;
    ReportDashboardDefinition dashboard = 3;
  }
}

message ReportDatasetSnapshot {
  string dataset_id = 1;
  uint64 version = 2;
  ReportDatasetDefinition definition = 3;
}

message ReportAssetRef {
  string profile_name = 1;
  string asset_id = 2;
}

message ReportAssetSummary {
  string id = 1;
  string title = 2;
  string description = 3;
  ReportAssetKind kind = 4;
  uint64 draft_revision = 5;
  uint64 published_version = 6;
  bool archived = 7;
  string updated_at = 8;
  repeated ReportCapability capabilities = 9;
}

message ReportAsset {
  ReportAssetSummary summary = 1;
  ReportDefinition definition = 2;
  repeated ReportDatasetSnapshot datasets = 3;
  string profile_name = 4;
  uint64 version = 5;
}

message ListReportAssetsRequest {
  string profile_name = 1;
  bool include_archived = 2;
}

message ListReportAssetsResponse {
  repeated ReportAssetSummary assets = 1;
  bool can_manage = 2;
}

message GetReportAssetRequest {
  ReportAssetRef asset = 1;
  ReportReadMode mode = 2;
  uint64 version = 3;
}

message SaveReportDraftRequest {
  ReportAssetRef asset = 1;
  uint64 expected_revision = 2;
  ReportDefinition definition = 3;
}

message ValidateReportRequest {
  ReportAssetRef asset = 1;
  uint64 expected_revision = 2;
}

message PublishReportRequest {
  ReportAssetRef asset = 1;
  uint64 expected_revision = 2;
}

message ReportVersionSummary {
  uint64 version = 1;
  string title = 2;
  string created_at = 3;
  string created_by = 4;
}

message ListReportVersionsResponse {
  repeated ReportVersionSummary versions = 1;
}

message RestoreReportDraftRequest {
  ReportAssetRef asset = 1;
  uint64 expected_revision = 2;
  uint64 version = 3;
}

message SetReportArchivedRequest {
  ReportAssetRef asset = 1;
  uint64 expected_revision = 2;
  bool archived = 3;
}

message ExecuteReportDatasetRequest {
  ReportAssetRef asset = 1;
  // Published version for viewer requests; draft revision for previews.
  uint64 version = 2;
  string dataset_id = 3;
  repeated ReportParameterBinding filters = 4;
  ReportExecutionPurpose purpose = 5;
  string panel_id = 6;
  uint32 action_index = 7;
}

message ReportPanelPreference {
  string panel_id = 1;
  uint32 width = 2;
  uint32 height = 3;
  bool hidden = 4;
}

message ReportPersonalView {
  string id = 1;
  string title = 2;
  uint64 report_version = 3;
  repeated ReportParameterBinding filters = 4;
  repeated ReportPanelPreference panels = 5;
  uint64 revision = 6;
}

message GetReportPersonalViewsResponse {
  repeated ReportPersonalView views = 1;
}

message SaveReportPersonalViewRequest {
  ReportAssetRef asset = 1;
  ReportPersonalView view = 2;
}

message DeleteReportPersonalViewRequest {
  ReportAssetRef asset = 1;
  string view_id = 2;
  uint64 expected_revision = 3;
}

message ReportMutationResult {
  bool success = 1;
}