conceptql 0.5.0 → 0.6.0

data/lib/conceptql/operators/hospitalization.rb

@@ -8,7 +8,7 @@ module ConceptQL
       register __FILE__
       include ConceptQL::Behaviors::Utilizable
 
-      desc "Selects admission records of type 'inpatient'"
+      desc "Selects inpatient admission records."
 
       def collection_type
         "inpatient"

data/lib/conceptql/operators/information_periods.rb

@@ -10,7 +10,10 @@ module ConceptQL
       include ConceptQL::Behaviors::Windowable
       include ConceptQL::Behaviors::Timeless
 
-      desc "Generates all observation_period records, or, if fed a stream, fetches all observation_period records for the people represented in the incoming record set."
+      desc "Selects all information period records, which have the observation_period domain. " \
+           "The operator takes no upstream stream. " \
+           "Each argument is an information type concept ID, and with arguments, " \
+           "the operator selects only the information periods of those types."
       domains :observation_period
       category "Get Related Data"
       basic_type :selection

data/lib/conceptql/operators/invalid.rb

@@ -8,13 +8,19 @@ module ConceptQL
       no_desc
       default_query_columns
 
+      # The statement [nil] or [""] has no operator name. It is named
+      # "invalid", as an empty statement is, so it does not report its error
+      # under the key "" (bead conceptql-1ci).
       def initialize(*args)
         super
+        @op_name = "invalid" if op_name.to_s.empty?
         @errors = @options.delete(:errors)
       end
 
+      # The name in the statement. Operator#operator_name would give the class
+      # name, "invalid", for every unknown operator.
       def operator_name
-        @operator_name ||= arguments.shift.to_s || "invalid"
+        op_name
       end
 
       def query(_db)

data/lib/conceptql/operators/multiple_vocabularies.rb

@@ -59,11 +59,25 @@ module ConceptQL
         # sharing a common table and feed them into a single single query,
         # but I think this would require some revamping of Vocabulary, and I'm
         # just not interested in taking that on right now.
+        all = disjoint_vocabularies?
         vocab_ops.map { |vo| vo.evaluate(db) }.inject do |union, q|
-          union.union(q.from_self)
+          union.union(q.from_self, all: all)
         end
       end
 
+      # Each vocabulary operator selects only the rows whose vocabulary column
+      # holds its own vocabulary. A row holds one vocabulary, and each output
+      # row carries its source row's id as criterion_id, so operators with
+      # different vocabularies on one column never produce the same row. Then
+      # UNION ALL skips a duplicate removal that is expensive on large data
+      # (conceptql-5pz). A repeated row inside one branch now passes through,
+      # as it does for a single vocabulary operator and for union. A custom
+      # file can list one vocabulary twice, so those branches keep UNION.
+      def disjoint_vocabularies?
+        conditions = vocab_ops.map(&:vocabulary_condition)
+        conditions.map(&:keys).uniq.length == 1 && conditions.uniq.length == conditions.length
+      end
+
       def domains(_db)
         vocab_ops.map(&:domain).uniq
       end
@@ -92,10 +106,9 @@ module ConceptQL
       end
 
       # The per-code warnings a Vocabulary operator gives, from most to least
-      # specific. See #code_warnings.
-      BAD_FORMAT = "improperly formatted code"
-      UNKNOWN_CODE = "unknown code(s)"
-      CODE_WARNINGS = [ BAD_FORMAT, UNKNOWN_CODE ].freeze
+      # specific (Operator::BAD_FORMATS, Operator::UNKNOWN_CODE). See
+      # #code_warnings.
+      CODE_WARNINGS = [ *BAD_FORMATS, UNKNOWN_CODE ].freeze
 
       def additional_validation(db, opts = {})
         vocab_ops.each { |vo| vo.valid?(db, opts) }
@@ -118,7 +131,7 @@ module ConceptQL
         end
 
         rejected = arguments.uniq.select { |code| verdicts.all? { |verdict| verdict.key?(code) } }
-        bad_format, unknown = rejected.partition { |code| verdicts.all? { |verdict| verdict[code] == BAD_FORMAT } }
+        bad_format, unknown = rejected.partition { |code| verdicts.all? { |verdict| BAD_FORMATS.include?(verdict[code]) } }
 
         [ [ BAD_FORMAT, *bad_format ], [ UNKNOWN_CODE, *unknown ] ].reject { |warning| warning.length == 1 }
       end

data/lib/conceptql/operators/numeric.rb

@@ -16,17 +16,11 @@ module ConceptQL
     class Numeric < PassThru
       register __FILE__
 
-      desc <<~EOF
-        Represents an operator that will either:
-        - Create a value_as_number value for every person in the database
-        - Change the value_as_number value for every record passed in
-          - Either to a number
-          - Or a value from a column in the origin row
-
-        Accepts two params:
-        - Either a number value or a symbol representing a column name
-        - An optional stream
-      EOF
+      desc "Sets the value_as_number of each record of its upstream stream. " \
+           "The argument is a number, or the name of a column whose value is copied from the same record. " \
+           "Without an upstream stream, the operator selects one person record for each person, " \
+           "with value_as_number set to the argument. " \
+           "A column name must then name a column of the person table."
       argument :value, type: :float
       allows_one_upstream
       validate_at_most_one_upstream
@@ -54,6 +48,39 @@ module ConceptQL
 
       private
 
+      # A column name in the argument must be a column of the rows it is read
+      # from, or the statement fails at run time. The match ignores case,
+      # because DuckDB and Spark resolve an identifier without regard to case,
+      # and such a statement runs on them today.
+      def additional_validation(_db, _opts = {})
+        name = column_argument
+        return if name.nil? || matched_column
+
+        add_error("unknown column", name)
+      end
+
+      # The column that the argument names, spelled as the rows spell it, or
+      # nil when the argument names no readable column. The SQL quotes the
+      # name, and Postgres folds only unquoted names, so the SQL must use this
+      # spelling for a match in another case to run there too.
+      def matched_column
+        name = column_argument
+        name && readable_columns.find { |column| column.to_s.casecmp?(name) }
+      end
+
+      # With an upstream, a column name is read from the upstream's rows
+      # (SELECT ... FROM (<upstream>)), not from the tables the upstream
+      # reads. Every stream emits the same columns, the scope's query columns,
+      # so one check covers an upstream that mixes tables, such as a union of
+      # two domains. Without an upstream, the name is read from the person
+      # table that as_criterion selects from, so it must be one of that
+      # table's columns in the data model's schema.
+      def readable_columns
+        return scope.query_columns if stream
+
+        dm.table_cols(dm.table_by_domain(:person))
+      end
+
       def with_kids(db)
         dm.selectify(db.from(stream.evaluate(db)), replace: { value_as_number: first_argument })
       end
@@ -79,15 +106,25 @@ module ConceptQL
       end
 
       def first_argument
-        value = arguments.first.to_s.strip
-        value = nil if value.blank?
+        value = argument_text
         if !value || is_a_number?(value)
           Sequel.cast_numeric(value, Float)
         else
-          Sequel.identifier(value)
+          Sequel.identifier(matched_column || value)
         end
       end
 
+      def argument_text
+        value = arguments.first.to_s.strip
+        value.blank? ? nil : value
+      end
+
+      # The argument when it names a column, or nil when it is a number or blank
+      def column_argument
+        value = argument_text
+        value if value && !is_a_number?(value)
+      end
+
       def is_a_number?(value)
         value =~ /\A[-+]?[0-9]*\.?[0-9]+\Z/
       end

data/lib/conceptql/operators/occurrence.rb

@@ -33,7 +33,9 @@ module ConceptQL
 
       preferred_name "Nth Occurrence"
 
-      desc "Groups all records by person, then orders by start_date and finds the nth occurrence. Can be positive or negative, e.g 2 means 'second' and -3 means 'third from last'."
+      desc "For each person, orders the records by start_date and passes along the record at the given position. " \
+           "A positive number counts from the earliest record, so 2 means the second record. " \
+           "A negative number counts from the most recent record, so -3 means the third record from the last."
 
       argument :occurrence, type: :integer
       category "Filter Single Stream"
@@ -73,7 +75,10 @@ module ConceptQL
         additional_order_columns = []
 
         if grouped?
-          one_date_ds = ds.from_self.where(rn: 1).from_self.select_remove(:rn)
+          # Name the columns to keep. select_remove(:rn) asked the database
+          # for them, and the CTE of a labeled upstream does not exist while
+          # the SQL is built (bead conceptql-6k8).
+          one_date_ds = ds.from_self.where(rn: 1).from_self.select(*dynamic_columns)
           ds = one_date_ds.select_append(
             Sequel[:ROW_NUMBER].function.over(
               partition: matching_columns_plus,
@@ -114,10 +119,17 @@ module ConceptQL
             ).as(:timed_rn)
           )
 
-        db[joined_name]
+        # Each first row nominates its nth rest row. With at_least, several
+        # first rows can nominate the same rest row: all rest rows that start
+        # after the same gap share one ranking. The join gives one row per
+        # nomination, so take the nominated rows from the input instead, and
+        # each comes out once (every stream is a set, seed conceptql-0eb).
+        nth_ds = db[joined_name].where(timed_rn: occurrence.abs)
+        keys = matching_columns_plus(:global_rn).map { |c| Sequel[:l][c] =~ Sequel[:r][c] }
+
+        rdbms.semi_join(db[input_name], nth_ds, *keys)
           .with(input_name, input_ds)
           .with(joined_name, joined_ds)
-          .where(timed_rn: occurrence.abs)
       end
 
       def grouped?

data/lib/conceptql/operators/operator.rb

@@ -33,6 +33,22 @@ module ConceptQL
 
       attr_reader :nodifier, :values, :options, :arguments, :upstreams, :op_name, :errors, :warnings
 
+      # The per-code warnings of a Vocabulary operator. A code that does not
+      # match its vocabulary's format is a warning, and the statement stays
+      # valid (Ryan ruled 2026-10-30, seeds conceptql-0eb and conceptql-ysx).
+      # The malformed code matches no rows. The formats come from
+      # vocabulary_formats (Vocabularies::Formats); a vocabulary without one
+      # is not checked. A well-formed code that the vocabulary does not know
+      # is also a warning.
+      BAD_FORMAT = "improperly formatted code"
+      # Claims carry the 11-digit package NDC (jde found no 9-digit product
+      # code in 601.9M claim NDCs, seed conceptql-ysx), so the NDC warning
+      # says why the code matches nothing. It starts with BAD_FORMAT, which
+      # the JDE algorithm spec looks for (bead conceptql-28h).
+      NDC_BAD_FORMAT = "#{BAD_FORMAT} (claims use 11-digit package NDCs, so it matches no rows)"
+      BAD_FORMATS = [ BAD_FORMAT, NDC_BAD_FORMAT ].freeze
+      UNKNOWN_CODE = "unknown code(s)"
+
       option :label, type: :string
 
       @validations = []
@@ -48,12 +64,6 @@ module ConceptQL
           end
         end
 
-        def query_columns(*tables)
-          define_method(:query_cols) do
-            dm.table_columns(*tables)
-          end
-        end
-
         def default_query_columns
           define_method(:query_cols) do
             dynamic_columns
@@ -86,9 +96,9 @@ module ConceptQL
           end
         end
 
-        # Declares inherited options that this operator does not support.
-        # They leave the operator's metadata, and a statement that sets one
-        # fails validation.
+        # Declares options that this operator does not support, inherited or
+        # not. An inherited one leaves the operator's metadata, and a
+        # statement that sets any of them fails validation.
         def unsupported_options(*names)
           names.each { |name| remove_option(name) }
           validations << [ :validate_unsupported_options, *names ]
@@ -170,15 +180,8 @@ module ConceptQL
         end
         res = [ op_name, *annotate_values(db, opts) ]
 
-        if upstreams_valid?(db, opts) && scope.valid? && include_counts?(db, opts)
-          scope.with_ctes(self, db)
-               .from_self
-               .select_group(:criterion_domain)
-               .select_append { Sequel.function(:count, 1).as(:rows) }
-               .select_append { count(:person_id).distinct.as(:n) }
-               .each do |h|
-            counts[h.delete(:criterion_domain).to_sym] = h
-          end
+        if countable?(db, opts)
+          counts.merge!(scope.one_query_counts&.for(self) || domain_counts(db))
         elsif !errors.empty?
           annotation[:errors] = errors
           scope.add_errors(scope_key, errors)
@@ -188,6 +191,9 @@ module ConceptQL
           cur_counts = counts[domain] ||= { rows: 0, n: 0 }
           scope.add_counts(scope_key, domain, cur_counts)
         end
+        # The database returns its groups in no fixed order, and the zero
+        # counts above come last. Sort them, so each run gives the same order.
+        annotation[:counts] = counts.sort.to_h
 
         if defined?(@warnings) && !warnings.empty?
           annotation[:warnings] = warnings
@@ -211,9 +217,15 @@ module ConceptQL
         "<##{self.class} upstreams=[#{upstreams.map(&:inspect).join(', ')}] arguments=[#{arguments.map(&:inspect).join(', ')}]>"
       end
 
+      # The operator's rows, read from a CTE that Scope#with_ctes moves to the
+      # statement's WITH list. With CONCEPTQL_AVOID_CTES, the rows are a
+      # subquery instead, because with_ctes then makes no WITH list.
       def evaluate(db)
         q = select_it(query(db))
+        return q.from_self if ConceptQL.avoid_ctes?
+
         name = cte_name(op_name)
+        scope.record_cte(self, name)
         opts = {}
         opts[:materialized] = true if rdbms.supports_materialized?
         db[name].with(name, q, opts)
@@ -322,6 +334,26 @@ module ConceptQL
         valid?(db, opts) && upstreams.all? { |u| u.upstreams_valid?(db, opts) }
       end
 
+      # Whether #annotate counts this operator's rows and people.
+      def countable?(db, opts = {})
+        upstreams_valid?(db, opts) && scope.valid? && include_counts?(db, opts)
+      end
+
+      # Rows and distinct people of each criterion_domain in this operator's
+      # output, with a query for this operator alone.
+      def domain_counts(db)
+        counts = {}
+        scope.with_ctes(self, db)
+             .from_self
+             .select_group(:criterion_domain)
+             .select_append { Sequel.function(:count, 1).as(:rows) }
+             .select_append { count(:person_id).distinct.as(:n) }
+             .each do |h|
+          counts[h.delete(:criterion_domain).to_sym] = h
+        end
+        counts
+      end
+
       def scope
         nodifier.scope
       end
@@ -503,6 +535,7 @@ module ConceptQL
         @errors = [] unless defined?(@errors)
         @warnings = [] unless defined?(@warnings)
 
+        add_warning("deprecated operator", self.class.deprecated) if self.class.deprecated
         add_error("invalid label") if label && !label.is_a?(String)
         self.class.validations.each do |args|
           send(*args)
@@ -588,7 +621,12 @@ module ConceptQL
       def validate_codes_match
         return if bad_arguments.empty?
 
-        add_warning("improperly formatted code", *bad_arguments)
+        add_warning(bad_format_message, *bad_arguments)
+      end
+
+      # The text of the format warning. Vocabulary gives the NDC its reason.
+      def bad_format_message
+        BAD_FORMAT
       end
 
       def additional_validation(_db, _opts = {})
@@ -634,8 +672,14 @@ module ConceptQL
         table = Sequel[table] if table.is_a?(Symbol)
         expr = exprs.inject(&:&)
         if use_inner_join?
+          # The join gives one copy of a left row for each matching right row.
+          # Every stream is a set (seed conceptql-0eb), so remove the copies.
+          # A caller can append right columns to the select list (temporal
+          # include_rhs_columns), and DISTINCT covers them: rows that differ
+          # by a right column stay (bead conceptql-3pr).
           ds.join(table.as(:r), expr)
             .select(*query_cols.map { |c| Sequel[:l][c] })
+            .distinct
         else
           rdbms.semi_join(ds, table, *exprs)
         end

data/lib/conceptql/operators/person.rb

@@ -10,7 +10,7 @@ module ConceptQL
 
       register __FILE__
 
-      desc "Selects all records in the person table."
+      desc "Selects all person records. With an upstream stream, the operator selects the person record of each person in that stream."
 
       allows_one_upstream
       domains :person

data/lib/conceptql/operators/person_filter.rb

@@ -10,6 +10,11 @@ module ConceptQL
       desc "Passes along left hand records with a corresponding person_id in the right hand records."
       default_query_columns
 
+      # PersonFilter has no `as` option, and a statement that sets one fails
+      # validation instead of running as a plain person_filter (bead
+      # conceptql-dlq).
+      unsupported_options :as
+
       def query(db)
         db.from(left.evaluate(db))
           .where(person_id: right.evaluate(db).from_self.select_group(:person_id))

data/lib/conceptql/operators/place_of_service_filter.rb

@@ -4,22 +4,37 @@ require_relative "operator"
 
 module ConceptQL
   module Operators
-    # Filters the incoming stream of records to only those that have a
-    # an associated visit_occurrence with the matching place_of_service
+    # Filters the incoming stream of records to only those whose place of
+    # service is one of the given codes of the CMS Place of Service
+    # vocabulary.
     #
-    # Provenance related concepts are the ones found in the xxx_type_concept_id
-    # field.
+    # A record's place of service is pos_concept_id: a column of the record's
+    # context in gdm and of observations in gdm_wide. The PoS query modifiers
+    # bring it into the stream as visit_source_concept_id.
     #
-    # If the record has NULL for the provenance-related field, they are filtered
-    # out.
+    # If the record has NULL for its place of service, it is filtered out.
     #
-    # Multiple provenances can be specified at once
+    # Multiple places of service can be specified at once. Each code becomes
+    # a concept ID through the lexicon, so a code that names no concept can
+    # match no record. Such a code is an error, as an unrecognized
+    # provenance keyword is.
+    #
+    # The code "*" keeps a record whose place of service is any concept of
+    # the vocabulary, as provenance's "*" keeps any provenance concept. A
+    # pos_concept_id of another vocabulary is not a place of service. Because
+    # codes are ORed, "*" with other codes is "*". The other codes are still
+    # checked.
     class PlaceOfServiceFilter < Operator
       register __FILE__
 
-      desc "Passes along records that match one or more of the Medicare Place Of Service values."
+      VOCABULARY_ID = "CMS Place of Service"
+      ANY = "*"
+
+      desc "Passes along the records whose place of service is one of the given CMS Place of Service codes. " \
+           "The code * matches a record that has any place of service. " \
+           "A record that has no place of service is not passed along."
 
-      argument :places_of_service, type: :codelist, vocab: "Place of Service"
+      argument :places_of_service, type: :codelist, vocab: VOCABULARY_ID
       category "Filter Single Stream"
       basic_type :temporal
       allows_one_upstream
@@ -35,8 +50,21 @@ module ConceptQL
 
       private
 
+      # With no codes, the lookup returns every concept of the vocabulary.
       def place_of_service_concept_ids(db)
-        dm.concept_ids(db, "Place of Service", arguments.map(&:to_s))
+        codes = arguments.map(&:to_s)
+        dm.concept_ids(db, VOCABULARY_ID, codes.include?(ANY) ? [] : codes)
+      end
+
+      # With no lexicon there are no codes to check against, and every code
+      # would be reported. Provenance skips its check in the same situation.
+      # A code is known only in its own case, as the lookup finds it.
+      def additional_validation(db, _opts = {})
+        return if dm.lexicon.strategy == :no_db
+
+        known = dm.concept_codes(db, VOCABULARY_ID)
+        unknown = arguments.reject { |code| code.to_s == ANY || known.include?(code.to_s) }
+        add_error(UNKNOWN_CODE, *unknown) unless unknown.empty?
       end
     end
   end

data/lib/conceptql/operators/provenance.rb

@@ -14,11 +14,19 @@ module ConceptQL
     # If the record has NULL for the provenance-related field, they are filtered
     # out.
     #
-    # Multiple provenances can be specified at once
+    # Multiple provenances can be specified at once. "*" asks for any
+    # provenance. At least one keyword is required.
     class Provenance < Operator
       register __FILE__
 
-      desc "Passes along records with the indicated provenance (e.g. inpatient, outpatient, file type)."
+      desc "Passes along the records whose provenance matches at least one of the given keywords. " \
+           "Each record has a file provenance, such as inpatient or outpatient, " \
+           "and a code provenance, such as primary or first. " \
+           "A plain keyword matches a record when either provenance matches it. " \
+           "A keyword of the form <file keyword>:<code keyword> matches a record when its file provenance " \
+           "matches the file keyword and its code provenance matches the code keyword. " \
+           "The keyword * matches a record that has any file or code provenance. " \
+           "At least one keyword is required."
 
       argument :provenance_types, label: "Provenance Types", type: :codelist
       category "Filter Single Stream"
@@ -39,6 +47,8 @@ module ConceptQL
       private
 
       def additional_validation(db, _opts = {})
+        return add_error('no provenance keywords; use "*" for any provenance') if arguments.empty?
+
         # With no lexicon there are no provenance concepts to check against,
         # and every keyword would be reported as unrecognized. Vocabulary
         # operators skip their unknown-code check in the same situation.

data/lib/conceptql/operators/provider_filter.rb

@@ -9,7 +9,11 @@ module ConceptQL
     class ProviderFilter < Operator
       register __FILE__
 
-      desc "Passes along records where the provider's specialty matches a given set of specialty_concept_ids.\n\nA single record may have multiple specialties, so the operator will return all records that match any of the given specialties, which may lead to duplicate records."
+      desc "Passes along the records whose provider matches the given specialties and roles. " \
+           "Each option is a comma-separated list of concept IDs, and * matches any value. " \
+           "A record matches the specialties when its context specialty or its practitioner specialty " \
+           "is in the list. " \
+           "A record can have more than one specialty, so the operator can pass along the same record more than once."
       option :specialties, type: :string
       option :roles, type: :string
       category "Filter Single Stream"

data/lib/conceptql/operators/race.rb

@@ -29,10 +29,6 @@ module ConceptQL
         @race_descendents ||= YAML.load_file(ConceptQL.race_file)
       end
 
-      def query_cols
-        table_columns(table)
-      end
-
       def table
         source_table
       end

data/lib/conceptql/operators/recall.rb

@@ -14,7 +14,7 @@ module ConceptQL
     class Recall < Operator
       register __FILE__
 
-      desc "Recalls a set of records from a labeled operator in the statement"
+      desc "Passes along the records of the operator in the statement that has the given label."
 
       argument :name, type: :string
       category "Get Related Data"

data/lib/conceptql/operators/snf.rb

@@ -8,10 +8,10 @@ module ConceptQL
       register __FILE__
       include ConceptQL::Behaviors::Utilizable
 
-      desc "Selects admission records of type 'SNF'"
+      desc "Selects skilled nursing facility (SNF) admission records."
 
       def collection_type
-        "SNF"
+        "snf"
       end
     end
   end

data/lib/conceptql/operators/sum.rb

@@ -8,7 +8,12 @@ module ConceptQL
       register __FILE__
 
       def events_per_patient
-        :multiple
+        group_by_person? ? :single : :multiple
+      end
+
+      # A person result per person, as the person cast gives (seed conceptql-6c3)
+      def domains(db)
+        group_by_person? ? [ :person ] : super
       end
 
       def multiple_vocabularies
@@ -17,16 +22,23 @@ module ConceptQL
         vocabularies.length > 1
       end
 
-      desc <<~EOF
-        Sums value_as_number across all records that match on all but start_date, end_date.
-        For start_date and end_date the min and max of each respectively is returned.'
-      EOF
+      desc "Groups the records that have the same values in all columns except criterion_id, start_date, " \
+           "end_date and value_as_number. For each group, the operator passes along one record " \
+           "with the sum of value_as_number, the earliest start_date, the most recent end_date " \
+           "and a criterion_id of 0. With group_by_person, the operator groups all of the records " \
+           "of each person and passes along one person record for each person."
+      option :group_by_person, type: :boolean,
+                               instructions: "Choose whether to sum all of the records of each person into one person record, for example to count the events of each person"
       default_query_columns
       validate_at_least_one_upstream
       validate_no_arguments
+      # The editor's checkbox sends true or false, and an unset field nil
+      validate_option ->(value) { [ true, false, nil ].include?(value) }, :group_by_person
       require_column :value_as_number
 
       def query(db)
+        return per_person_query(db) if group_by_person?
+
         db.from(unioned(db))
           .select_group(*(dynamic_columns - %i[start_date end_date criterion_id value_as_number]))
           .select_append(Sequel.lit("?", 0).as(:criterion_id))
@@ -36,6 +48,35 @@ module ConceptQL
           .from_self
       end
 
+      # One row for each person (and window): the earliest start_date, the
+      # latest end_date and the sum of value_as_number. criterion_table,
+      # criterion_domain and column_family are those of the person cast. No
+      # single record stands behind the row, so criterion_id is 0 and the
+      # other columns are NULL.
+      def per_person_query(db)
+        person = {
+          criterion_id: Sequel.lit("?", 0),
+          criterion_table: Sequel.cast_string(dm.table_by_domain(:person).to_s),
+          criterion_domain: Sequel.cast_string("person"),
+          column_family: Sequel.cast_string(ConceptQL::Scope::DEFAULT_COLUMN_FAMILY)
+        }
+        aggregated = %i[start_date end_date value_as_number]
+        nulls = dynamic_columns - matching_columns - person.keys - aggregated
+
+        db.from(unioned(db))
+          .select_group(*matching_columns)
+          .select_append(*person.map { |column, value| value.as(column) })
+          .select_append { min(start_date).as(:start_date) }
+          .select_append { max(end_date).as(:end_date) }
+          .select_append { sum(value_as_number).as(:value_as_number) }
+          .select_append(*nulls.map { |column| rdbms.process(column, nil) })
+          .from_self
+      end
+
+      def group_by_person?
+        options[:group_by_person]
+      end
+
       def unioned(db)
         upstreams.map { |c| c.evaluate(db).select(*query_cols) }.inject do |uni, q|
           uni.union(q.from_self)

data/lib/conceptql/operators/temporal_operator.rb

@@ -99,8 +99,12 @@ module ConceptQL
       def apply_selectors(ds, opts = {})
         return ds unless include_rhs_columns
 
-        ds = ds.select_remove(*include_rhs_columns).select_append(*rhs_columns(opts)) if include_rhs_columns
-        ds
+        # A dataset without a select list reads an upstream, so it has the
+        # scope's columns. Name them: select_remove would ask the database
+        # for them, and the CTE of a labeled upstream does not exist while
+        # the SQL is built (bead conceptql-6k8).
+        ds = ds.select(*dynamic_columns) if ds.opts[:select].blank?
+        ds.select_remove(*include_rhs_columns).select_append(*rhs_columns(opts))
       end
 
       def rhs_columns(opts)