strata-cli 0.1.11 → 0.1.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 371199d421786d4bc06748770b1155f59206d49f115eb0d2c664df2a0de139d8
-  data.tar.gz: eb1ecac2dc8e40864f5c8ad278353ed8b8924f99fc54a2dad5c356f63dacd06d
+  metadata.gz: 61be99c9ce107eae809e67fa23dd4108a471dcc90b6adb039a298b5d59005106
+  data.tar.gz: '080076fa7d113e1e066caca27a3e33e3c438a0bb8d2e53a602ed75cf7a5b5ec5'
 SHA512:
-  metadata.gz: 6f65de98ebf7994129da1cc2b6ae16a3591020e799ab61583afb1eea725f69b73fa6e35f3d8e69ebe0540bf8cdfe02f38a2f8d9f5c9e2ca606d0bf81536fa1d1
-  data.tar.gz: f6e89761a4ef0fd8586d8a82a4262594f22f95a14f814abc6b48ab2d62e20e840429ee0dbf215dc58f2c8a4d350eace329d7be6528f1a079b2fb17a223cf88c2
+  metadata.gz: eaac835415776492c4858204340238a71fc9a8e45ad61183d46f532a22723774d39a16e9dfb30db5841bc897a12547a9a8fe93c1543e3b7e1975daecdf5b2d82
+  data.tar.gz: d443533139c4aea533e2bf0fd2d3f14e7de3bf7f1bb87e004e174a7232802b8c9086c7e470bb1640c697522fad07445db6bbfa60185e1a667fbe0f7c838ede58

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 ## [Unreleased]
 
+## [0.1.13] - 2026-06-20
+
+### Changed
+
+- **Documentation**: ClickHouse adapter docs in README, gemspec description, `datasource add` help text, and CHANGELOG notes for the 0.1.12 feature set.
+
+## [0.1.12] - 2026-06-20
+
+### Added
+
+- **ClickHouse adapter**: `strata datasource add clickhouse` with connection prompts and optional password credentials.
+- **Security policy scaffolding**: `strata create policy` to add policies to `security.yml`; new projects include a `security.yml` template.
+
+### Changed
+
+- **dwh dependency**: Require `dwh` `~> 0.5.0` (ClickHouse adapter and dialect keyword/aggregate support).
+
+### Fixed
+
+- **Datasource introspection**: Pass only `catalog` and `schema` qualifiers to DWH for `tables` and `meta` (avoids leaking CLI flags like `--agent` or `--pattern` to adapters).
+
 ## [0.1.11] - 2026-05-22
 
 ### Changed

data/README.md

@@ -375,6 +375,17 @@ my_databricks:
   catalog: main
   schema: default
   auth_mode: oauth_m2m
+
+my_clickhouse:
+  adapter: clickhouse
+  name: ClickHouse
+  protocol: http
+  host: localhost
+  port: 8123
+  database: default
+  username: default
+  tier: warm
+  query_timeout: 3600
 ```
 
 ### Databricks authentication
@@ -403,6 +414,7 @@ Use service principal credentials and run `strata ds auth my_databricks` to save
 - **Druid** - Apache Druid support
 - **Redshift** - Amazon Redshift support
 - **Databricks** - Databricks SQL warehouse support
+- **ClickHouse** - ClickHouse HTTP/native SQL support
 - **SQLite** - SQLite database support
 
 ## Security

data/lib/strata/cli/credentials.rb

@@ -48,6 +48,8 @@ module Strata
           credentials["auth_mode"] = "oauth_m2m"
           credentials["oauth_client_id"] = @prompt.ask("OAuth Client ID:")
           credentials["oauth_client_secret"] = @prompt.ask("OAuth Client Secret:")
+        when "clickhouse"
+          credentials["password"] = @prompt.mask("Enter Password (leave blank if none):")
         else
           if required?
             unless %w[postgres mysql trino sqlserver].include?(adapter)

data/lib/strata/cli/descriptions/datasource/add.txt

@@ -18,4 +18,4 @@ Examples:
 
   strata datasource add snowflake        # Directly add Snowflake datasource
 
-Supported adapters: postgres, mysql, sqlserver, snowflake, athena, trino, duckdb, druid
+Supported adapters: postgres, mysql, sqlserver, snowflake, athena, trino, duckdb, druid, clickhouse, databricks, redshift, sqlite

data/lib/strata/cli/generators/policy.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative "group"
+require_relative "../output"
+
+module Strata
+  module CLI
+    module Generators
+      # Appends a new policy entry to the project's security.yml.
+      # Receives a fully-resolved attrs hash from the Create subcommand.
+      class Policy < Group
+        argument :attrs, type: :hash
+
+        def append_policy_to_security_yml
+          security_file = "security.yml"
+
+          unless File.exist?(security_file)
+            raise Strata::CommandError,
+              "security.yml not found in the current directory. Run 'strata init' first."
+          end
+
+          content = File.read(security_file)
+          new_entry = format_policy_yaml(attrs)
+
+          updated = if content.match?(/^policies:\s*\[\]/)
+            # First policy — replace inline empty array with block sequence
+            content.sub(/^policies:\s*\[\]/, "policies:\n#{new_entry}")
+          else
+            # Subsequent policy — append after existing entries
+            content.rstrip + "\n#{new_entry}"
+          end
+
+          File.write(security_file, updated)
+          Output.print_status(:updated, security_file, type: :success, context: self)
+        end
+
+        private
+
+        def format_policy_yaml(a)
+          lines = []
+          lines << "  - name: #{a[:name]}"
+          lines << "    mode: #{a[:mode]}"
+          lines << "    mask_value: \"#{a[:mask_value]}\"" if a[:mode] == "mask_data"
+          lines << "    triggers:"
+
+          tags = Array(a[:field_tags])
+          lines << "      field_tags: [#{tags.join(", ")}]"
+
+          field_names = Array(a[:field_names]).reject(&:empty?)
+          unless field_names.empty?
+            lines << "      field_names:"
+            field_names.each { |n| lines << "        - #{n}" }
+          end
+
+          lines << "    context_dimension: #{a[:context_dimension]}"
+          lines << "    permission_resolution:"
+          lines << "      source: #{a[:permission_source]}"
+          lines << "      value_from: #{a[:value_from]}"
+          lines << "      tag_key: #{a[:tag_key]}" if a[:tag_key].to_s.strip.length > 0
+          lines << "    bypass:"
+          lines << "      system_admin: #{a[:bypass_system_admin]}"
+          lines << "      project_admin: #{a[:bypass_project_admin]}"
+          lines.join("\n") + "\n"
+        end
+      end
+    end
+  end
+end

data/lib/strata/cli/generators/project.rb

@@ -57,7 +57,7 @@ module Strata
         def create_project_structure
           return if cloned_from_git?
 
-          empty_directory uid
+          empty_directory uid unless existing_directory?
           empty_directory File.join(uid, "models")
           empty_directory File.join(uid, "tests")
         end
@@ -102,6 +102,12 @@ module Strata
           end
         end
 
+        def create_security_file
+          return if cloned_from_git?
+
+          copy_file "security.yml", "#{uid}/security.yml"
+        end
+
         def initialize_git
           return if cloned_from_git?
 
@@ -113,7 +119,8 @@ module Strata
 
         def setup_datasource
           return if cloned_from_git?
-          return if options.key?(:datasource) # Already specified via CLI option
+          return if options.key?(:datasource)
+          return if existing_directory?
 
           print_status(:setup, "Let's configure your first datasource", type: :info)
           print_info("\n")
@@ -140,6 +147,10 @@ module Strata
           @cloned_from_git ||= false
         end
 
+        def existing_directory?
+          File.directory?(name.to_s)
+        end
+
         def fetch_project_info
           conn = Faraday.new(url: options[:source]) do |f|
             f.request :authorization, "Bearer", options[:api_key]
@@ -180,6 +191,8 @@ module Strata
         def uid
           @uid ||= if options.key?(:source) && @project_info
             @project_info["uid"] || options[:source].split("/").last
+          elsif existing_directory?
+            name.to_s
           else
             Utils.url_safe_str(name)
           end

data/lib/strata/cli/generators/templates/AGENTS.md

@@ -28,11 +28,13 @@ Read this file end-to-end before creating or editing `models/**/*.yml`. Do not m
 
 These are non-negotiable. Violations break deploy, query planning, or production reports.
 
-1. **Every field `name` is unique project-wide** — one name = one dimension or measure entity across all `tbl.*.yml` files. Strata has no `table.field` namespaces; bracket references like `[Total Revenue]` resolve by name alone.
+1. **Every field `name` is unique project-wide per dimension or measure** — one name = one dimension or measure entity across all `tbl.*.yml` files. Strata has no `table.field` namespaces; bracket references like `[Total Revenue]` resolve by name alone.
 2. **`many_to_many` join cardinality is not supported.** Use a junction/bridge table with two relationships (`one_to_many` + `many_to_one`) instead.
 3. **Measures on unrelated detail facts must have distinct names** — e.g. `Store Gross Sales`, `Catalog Gross Sales`, not one `Gross Sales` on three channel facts. See [Naming conventions](#naming-conventions).
-4. **Dimensions may share names** when the business role is the same; Strata picks among tables at query time. **Measures do not combine that way** — duplicate measure names attach more SQL to the same measure entity (double-count risk).
+4. **Dimensions may share names** when the business role is the same; Strata picks among tables at query time. **Measures do not combine that way** — duplicate measure names implies varying levels of aggregation of the same basic fact. The correct table and measure combination will be determined by context (i.e. what dimensions are present in the same query.)
 5. **Cross-fact totals use compound measures or blending** — not the same measure name on multiple facts. See [Combined metrics across facts](#combined-metrics-across-facts).
+6. Security policies can be implemented in the security.yml file.  Use the guidelines documented therin.
+7. Strata supports role playing or aliasing of dimension tables.  For example, user wants date_dim table to also be used when query "Order Return Date". In that case, we simply point to the same physical_name "date_dim" but set the table name to "Order Return Date". If the user asks to alias an dimension table from an existing model we can simply copy the existing model, change the table name, and prefix all the dimensions in it with the appropriate prefix representing the role.
 
 ## Unsupported or impossible requirements
 

data/lib/strata/cli/generators/templates/security.yml

@@ -0,0 +1,77 @@
+# Semantic Security Policies
+#
+# This file defines row-level security policies enforced at query planning time.
+# Policies are branch-scoped and deployed alongside your semantic model.
+#
+# Two enforcement modes:
+#
+#   mask_data   — Sensitive column values are replaced with a mask string.
+#                 Rows remain in the result set; users can see that restricted
+#                 data exists but cannot read it.
+#
+#   filter_data — Rows for context values the user cannot access are removed
+#                 entirely. Restricted data is invisible to the user.
+#
+# How it works:
+#   1. A policy is triggered when a query projects a field tagged with one of
+#      the trigger tags (e.g. "pii").
+#   2. The context_dimension defines the security boundary (e.g. "Call Center ID").
+#      It must be reachable in every universe that contains a triggered field,
+#      otherwise the query is rejected with a hard error.
+#   3. Permission resolution determines which context dimension values the current
+#      user is allowed to see, derived from their group memberships or user record.
+#
+# Tagging fields: add a tags key to any dimension in your table YAML files:
+#
+#   fields:
+#     - type: dimension
+#       name: Agent Name
+#       tags: [pii]
+#       data_type: string
+#       expression:
+#         sql: agent_name
+
+policies: []
+
+# ── Example: mask PII dimensions scoped by call center ──────────────────────
+#
+# - name: PII Call Center Masking
+#   mode: mask_data              # mask_data | filter_data
+#   mask_value: "#######"        # Value shown to users without access (mask_data only)
+#
+#   triggers:
+#     field_tags: [pii]          # Triggers on any field tagged "pii"
+#     # field_names:             # Optional: trigger on specific fields by display name
+#     #   - Agent Name           # Resolved to UIDs at deploy time
+#
+#   # Dimension that scopes visibility. Resolved by name at deploy time.
+#   # Must be reachable in the universe for any query that includes a triggered field.
+#   context_dimension: Call Center ID
+#
+#   permission_resolution:
+#     source: groups             # groups | user
+#     value_from: tag            # groups: name | tag   /   user: email | tag
+#     tag_key: call_center_id   # Required when value_from is "tag".
+#                                # Extracts the value from group tags formatted as "call_center_id:TMNT"
+#
+#   bypass:
+#     system_admin: true         # System admins bypass this policy entirely
+#     project_admin: false
+#
+# ── Example: filter rows so each user sees only their own employee record ────
+#
+# - name: Employee Self-Service
+#   mode: filter_data
+#
+#   triggers:
+#     field_tags: [employee_pii]
+#
+#   context_dimension: Employee Email
+#
+#   permission_resolution:
+#     source: user               # Resolve from the current user's own attributes
+#     value_from: email          # Allowed value = the authenticated user's email address
+#
+#   bypass:
+#     system_admin: true
+#     project_admin: false

data/lib/strata/cli/helpers/prompts.rb

@@ -28,6 +28,21 @@ module Strata
       MSG_MODELS_LIST_HEADER = "\n  Semantic Models:\n"
       MSG_MODELS_COUNT = "\n  Total: %d model(s)\n"
 
+      # Policy Command Prompts
+      MSG_POLICY_NAME = "  Policy name:"
+      MSG_POLICY_MODE = "  Enforcement mode:"
+      MSG_POLICY_MASK_VALUE = "  Mask value (shown for restricted data):"
+      MSG_POLICY_FIELD_TAGS = "  Field tags that trigger this policy (comma-separated, e.g. pii,hipaa):"
+      MSG_POLICY_FIELD_NAMES = "  Specific field names (comma-separated, optional — leave blank to skip):"
+      MSG_POLICY_CONTEXT_DIM = "  Context dimension name:"
+      MSG_POLICY_PERM_SOURCE = "  Permission source:"
+      MSG_POLICY_VALUE_FROM = "  Resolve allowed values from:"
+      MSG_POLICY_TAG_KEY = "  Tag key (e.g. call_center_id):"
+      MSG_POLICY_BYPASS_ADMIN = "  Bypass for system admins?"
+      MSG_POLICY_BYPASS_PROJECT = "  Bypass for project admins?"
+      MSG_POLICY_CREATED = "\n✔ Policy '%s' added to security.yml"
+      MSG_POLICY_HINT = "\n💡 Run 'strata deploy' to activate this policy"
+
       # Migration hook options
       MIGRATION_HOOK_OPTIONS = {
         "pre (before deployment)" => "pre",

data/lib/strata/cli/sub_commands/audit.rb

@@ -30,7 +30,7 @@ module Strata
         ALLOWED_FIELD_KEYS = %w[
           type name description hidden grains data_type display_type format
           secure disable_listing value_list_size snapshot exclusion_type
-          exclusions inclusions extended_blend_group synonyms expression
+          exclusions inclusions extended_blend_group synonyms expression tags
         ].freeze
         ALLOWED_EXPRESSION_KEYS = %w[sql array lookup primary_key].freeze
         EXPRESSION_BOOLEAN_KEYS = %w[array lookup primary_key].freeze

data/lib/strata/cli/sub_commands/create.rb

@@ -51,6 +51,21 @@ module Strata
           end
         end
 
+        desc "policy [NAME]", "Scaffold a new security policy in security.yml"
+        method_option :interactive, aliases: "-i", type: :boolean, default: false,
+          desc: "Walk through all options interactively"
+        method_option :mode, type: :string, desc: "Enforcement mode: mask_data or filter_data"
+        method_option :tags, type: :array, desc: "Field tags that trigger this policy"
+        method_option :context, type: :string, desc: "Context dimension name"
+
+        def policy(name = nil)
+          attrs = policy_interactive_mode? ? collect_policy_interactive(name) : collect_policy_fast(name)
+          require_relative "../generators/policy"
+          Generators::Policy.new([attrs]).invoke_all
+          say MSG_POLICY_CREATED % attrs[:name], :green
+          say MSG_POLICY_HINT, :yellow
+        end
+
         desc "relation RELATION_PATH", "Create a relation (join) definition file"
         long_desc_from_file("create/relation")
 
@@ -122,6 +137,94 @@ module Strata
 
         private
 
+        # ── Policy helpers ────────────────────────────────────────────────────
+
+        def policy_interactive_mode?
+          options[:interactive] ||
+            (options[:mode].nil? && options[:tags].nil? && options[:context].nil?)
+        end
+
+        def collect_policy_fast(name)
+          {
+            name: name || "New Policy",
+            mode: options[:mode] || "mask_data",
+            mask_value: "#######",
+            field_tags: Array(options[:tags]),
+            field_names: [],
+            context_dimension: options[:context] || "<context_dimension>",
+            permission_source: "groups",
+            value_from: "tag",
+            tag_key: "<tag_key>",
+            bypass_system_admin: true,
+            bypass_project_admin: false
+          }
+        end
+
+        def collect_policy_interactive(name)
+          say "\n  Policy\n", :bold
+          policy_name = name || prompt.ask(MSG_POLICY_NAME) { |q| q.required true }
+
+          mode = prompt.select(MSG_POLICY_MODE, [
+            {name: "mask_data  — replace restricted values with a mask", value: "mask_data"},
+            {name: "filter_data — remove restricted rows entirely", value: "filter_data"}
+          ])
+
+          mask_value = if mode == "mask_data"
+            prompt.ask(MSG_POLICY_MASK_VALUE, default: "#######")
+          end
+
+          say "\n  Triggers\n", :bold
+          tags_raw = prompt.ask(MSG_POLICY_FIELD_TAGS, default: "")
+          field_tags = tags_raw.to_s.split(",").map(&:strip).reject(&:empty?)
+
+          names_raw = prompt.ask(MSG_POLICY_FIELD_NAMES, default: "")
+          field_names = names_raw.to_s.split(",").map(&:strip).reject(&:empty?)
+
+          say "\n  Context\n", :bold
+          context_dimension = prompt.ask(MSG_POLICY_CONTEXT_DIM) { |q| q.required true }
+
+          say "\n  Permission Resolution\n", :bold
+          permission_source = prompt.select(MSG_POLICY_PERM_SOURCE, [
+            {name: "groups — derive from the user's group memberships", value: "groups"},
+            {name: "user   — derive from the user's own attributes", value: "user"}
+          ])
+
+          value_from_choices = if permission_source == "groups"
+            [
+              {name: "tag  — extract value from a group tag (e.g. call_center_id:TMNT)", value: "tag"},
+              {name: "name — use the group's display name as the allowed value", value: "name"}
+            ]
+          else
+            [
+              {name: "email — the user's email address", value: "email"},
+              {name: "tag   — extract value from a user tag", value: "tag"}
+            ]
+          end
+          value_from = prompt.select(MSG_POLICY_VALUE_FROM, value_from_choices)
+
+          tag_key = if value_from == "tag"
+            prompt.ask(MSG_POLICY_TAG_KEY) { |q| q.required true }
+          end
+
+          say "\n  Bypass\n", :bold
+          bypass_system_admin = prompt.yes?(MSG_POLICY_BYPASS_ADMIN, default: true)
+          bypass_project_admin = prompt.yes?(MSG_POLICY_BYPASS_PROJECT, default: false)
+
+          {
+            name: policy_name,
+            mode: mode,
+            mask_value: mask_value,
+            field_tags: field_tags,
+            field_names: field_names,
+            context_dimension: context_dimension,
+            permission_source: permission_source,
+            value_from: value_from,
+            tag_key: tag_key,
+            bypass_system_admin: bypass_system_admin,
+            bypass_project_admin: bypass_project_admin
+          }
+        end
+
         def handle_table_creation_with_path(table_path)
           # Parse the path to extract schema, physical name, and model path
           parsed = parse_table_path(table_path)

data/lib/strata/cli/sub_commands/datasource.rb

@@ -187,7 +187,7 @@ module Strata
           return unless ds_key
 
           adapter = create_adapter(ds_key)
-          tables = adapter.tables(**options)
+          tables = adapter.tables(**adapter_qualifiers)
           tables = tables.select { it =~ /#{options[:pattern]}/ } if options[:pattern]
 
           if agent_mode?
@@ -214,7 +214,7 @@ module Strata
         method_option :schema, aliases: "s", type: :string, desc: "Change the schema from the configured one."
         def meta(ds_key, table_name)
           adapter = create_adapter(ds_key)
-          md = adapter.metadata(table_name, **options.transform_keys(&:to_sym))
+          md = adapter.metadata(table_name, **adapter_qualifiers)
 
           if agent_mode?
             columns = md.columns.map do |column|
@@ -275,6 +275,10 @@ module Strata
           false
         end
 
+        def adapter_qualifiers
+          options.transform_keys(&:to_sym).slice(:catalog, :schema)
+        end
+
         def validate_file_path(file_path, project_path = Dir.pwd)
           expanded = File.expand_path(file_path, project_path)
           project_root = File.expand_path(project_path)
@@ -370,6 +374,14 @@ module Strata
               "schema" => "default",
               "auth_mode" => "oauth_m2m"
             }
+          when "clickhouse"
+            {
+              "protocol" => "http",
+              "host" => "localhost",
+              "port" => 8123,
+              "database" => "test_db",
+              "username" => "default"
+            }
           else
             {}
           end

data/lib/strata/cli/version.rb

@@ -2,6 +2,6 @@
 
 module Strata
   module CLI
-    VERSION = "0.1.11"
+    VERSION = "0.1.13"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: strata-cli
 version: !ruby/object:Gem::Version
-  version: 0.1.11
+  version: 0.1.13
 platform: ruby
 authors:
 - Ajo Abraham
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.4.2
+        version: 0.5.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.4.2
+        version: 0.5.0
 - !ruby/object:Gem::Dependency
   name: aws-sdk-athena
   requirement: !ruby/object:Gem::Requirement
@@ -224,7 +224,7 @@ description: |
   Comprehensive CLI tool for managing Strata Semantic Analytics projects. Create and initialize
   projects, manage datasource connections, build semantic table models with AI assistance, run
   audits and validations, and deploy projects to Strata servers. Supports multiple data warehouse
-  adapters including PostgreSQL, MySQL, SQL Server, Snowflake, Athena, Trino, and more.
+  adapters including PostgreSQL, MySQL, SQL Server, Snowflake, Athena, Trino, ClickHouse, and more.
 email:
 - ajo@strata.site
 - allen@strata.site
@@ -268,6 +268,7 @@ files:
 - lib/strata/cli/generators/datasource.rb
 - lib/strata/cli/generators/group.rb
 - lib/strata/cli/generators/migration.rb
+- lib/strata/cli/generators/policy.rb
 - lib/strata/cli/generators/project.rb
 - lib/strata/cli/generators/relation.rb
 - lib/strata/cli/generators/table.rb
@@ -286,6 +287,7 @@ files:
 - lib/strata/cli/generators/templates/migration.swap.yml
 - lib/strata/cli/generators/templates/project.yml
 - lib/strata/cli/generators/templates/rel.domain.yml
+- lib/strata/cli/generators/templates/security.yml
 - lib/strata/cli/generators/templates/strata.yml
 - lib/strata/cli/generators/templates/table.table_name.yml
 - lib/strata/cli/generators/templates/test.yml