plume 0.1.0 → 0.3.0

data/lib/plume/analysis.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+module Plume
+	# Static analysis on top of the AST. The first question it answers is "which tables and
+	# columns would this statement read?", see `Plume.reads`; the second is what it would
+	# write, see `Plume.writes`.
+	module Analysis
+		autoload :Resolver, "plume/analysis/resolver"
+
+		# A read or write of one column, or of a table as a whole when `column` is nil - which is
+		# what `SELECT count(*) FROM t` or `DELETE FROM t` amount to.
+		#
+		# For reads, `usage` is `:projected` when the value itself can leave the statement - in the
+		# result rows, through RETURNING, or copied into a column being written - and `:referenced`
+		# when it is only used to filter, join, sort or group. For writes it is `:insert`,
+		# `:update` or `:delete`.
+		Reference = Data.define(:schema, :table, :column, :usage, :node) do
+			def table_key = Analysis.table_key(schema, table)
+		end
+
+		Unresolved = Data.define(:name, :reason, :node) do
+			def message
+				excerpt = Analysis.excerpt(node)
+				excerpt ? "#{reason}: #{name}\n#{excerpt}" : "#{reason}: #{name}"
+			end
+		end
+
+		# The source line `node` sits on with a caret under it, for error messages
+		def self.excerpt(node)
+			loc = node&.location
+			Plume.excerpt(node.full_source, *loc) if loc && node.full_source
+		end
+
+		class Error < StandardError
+			attr_reader :unresolved
+
+			def initialize(message = nil, unresolved: [])
+				@unresolved = unresolved
+				super(message || unresolved.map(&:message).join("\n"))
+			end
+		end
+
+		# Tables in the main schema are keyed by their bare name, any other schema
+		# (temp, attached databases) is spelled out as "schema.table"
+		def self.table_key(schema, table)
+			(schema.nil? || schema.casecmp("main")&.zero?) ? table : "#{schema}.#{table}"
+		end
+
+		class References
+			# `ctes` are the names the statement's WITH clauses define, `aliases` maps each table alias
+			# to the table, view, CTE or function it stands for - all spelled as written, and none from
+			# inside the views read. Reads and Writes of one statement share them
+			attr_reader :statement, :references, :unresolved, :ctes, :aliases
+
+			def initialize(statement, unresolved = [], ctes = Set.new, aliases = {})
+				@statement = statement
+				@references = []
+				@unresolved = unresolved
+				@ctes = ctes
+				@aliases = aliases
+			end
+
+			# Every base table touched, including ones touched only as a whole
+			def tables(usage = nil) = @references.select { |r| usage.nil? || r.usage == usage }.to_set(&:table_key)
+
+			# `{ "table" => Set["column", …] }`, optionally narrowed to one usage
+			def columns(usage = nil)
+				@references.each_with_object({}) do |ref, acc|
+					next if ref.column.nil? || (usage && ref.usage != usage)
+
+					(acc[ref.table_key] ||= Set.new) << ref.column
+				end
+			end
+
+			def resolved? = @unresolved.empty?
+
+			def inspect
+				"#<#{self.class.name} columns=#{columns.transform_values(&:to_a).inspect} unresolved=#{@unresolved.size}>"
+			end
+		end
+
+		class Reads < References
+			# `functions` are the table-valued ones in FROM, `calls` every other function called -
+			# including those LIKE, GLOB, REGEXP, MATCH, `->`, `->>` and CURRENT_* call - as SQLite's
+			# authorizer reports them
+			attr_reader :views, :functions, :calls
+
+			def initialize(...)
+				super
+				@views = Set.new
+				@functions = Set.new
+				@calls = Set.new
+			end
+
+			def projected = columns(:projected)
+			def referenced = columns(:referenced)
+		end
+
+		class Writes < References
+			# INSERT without a column list writes every column; without a catalog that is "*"
+			def inserted = columns(:insert)
+			def updated = columns(:update)
+			def deleted = tables(:delete)
+		end
+
+		# What a run of statements reads, writes and does, as `Plume.summary` gives it. `accesses` has one
+		# entry per statement, the rest is merged across them
+		class Summary
+			attr_reader :statements, :accesses
+
+			def initialize(statements, accesses)
+				@statements = statements
+				@accesses = accesses
+			end
+
+			# Each statement's node class, like "SelectStatement" or "CreateTableStatement"
+			def statement_types = @statements.map { |s| s.class.name.delete_prefix("Plume::") }
+
+			# Every base table read or written, or only those touched in one way: `:projected`,
+			# `:referenced`, `:insert`, `:update` or `:delete`
+			def tables(usage = nil) = each_side.reduce(Set.new) { |all, refs| all | refs.tables(usage) }
+
+			def reads = @accesses.map(&:reads)
+			def writes = @accesses.map(&:writes)
+			def actions = @accesses.flat_map(&:actions)
+			def views = union(reads, :views)
+			def functions = union(reads, :functions)
+			def calls = union(reads, :calls)
+			def ctes = union(reads, :ctes)
+			def aliases = reads.reduce({}) { |all, r| all.merge(r.aliases) }
+			def unresolved = reads.flat_map(&:unresolved)
+			def resolved? = unresolved.empty?
+
+			private
+
+			def each_side = reads + writes
+			def union(list, name) = list.reduce(Set.new) { |all, r| all | r.public_send(name) }
+		end
+
+		# Something a statement does besides reading and writing rows, named as SQLite's authorizer
+		# names it: `action` is its action code as a symbol (`:create_table`, `:drop_temp_index`,
+		# `:alter_table`, `:pragma`, `:transaction`…), and `name`, `detail` and `schema` are the
+		# arguments the authorizer gets with it - for `:create_index`, the index, its table and the schema
+		Action = Data.define(:action, :name, :detail, :schema, :node)
+
+		Access = Data.define(:reads, :writes, :actions) do
+			def unresolved = reads.unresolved
+			def resolved? = reads.resolved?
+		end
+	end
+
+	module Analysis
+		# Which tables and columns `sql` - a single SELECT, INSERT, UPDATE or DELETE - would read.
+		# Instead of SQL you can pass what you already parsed: a statement node, or the array
+		# `Plume.parse` returns, so the same SQL does not get parsed twice.
+		#
+		# Without a catalog, columns of tables cannot be enumerated: `SELECT *` comes back as a read
+		# of the column "*", and an unqualified column with more than one table in scope is ambiguous.
+		#
+		# With `strict: true` (the default) anything that cannot be attributed raises
+		# `Plume::Analysis::Error`; with `strict: false` it is listed in `Reads#unresolved` instead.
+		def self.reads(sql, catalog: nil, strict: true) = access(sql, catalog:, strict:).reads
+
+		# Which tables and columns an INSERT, UPDATE or DELETE would write, with the same arguments
+		# and strictness as `reads`. A SELECT writes nothing. The triggers a statement fires are not looked into, so rows
+		# they write elsewhere - or the rows a REPLACE deletes - are not reported.
+		def self.writes(sql, catalog: nil, strict: true) = access(sql, catalog:, strict:).writes
+
+		# Like `reads`, but also reports what an INSERT, UPDATE or DELETE writes, and in `actions` what
+		# any other statement does - creating, dropping and altering things, pragmas, transactions. A
+		# CREATE TRIGGER is analyzed for what its WHEN and body do each time it fires, a CREATE TABLE … AS
+		# reads what its SELECT reads, a CREATE INDEX reads what it indexes, DROP TABLE deletes the rows
+		def self.access(sql, catalog: nil, strict: true)
+			statements = statements(sql)
+			raise Error, "expected exactly one statement, got #{statements.size}" unless statements.size == 1
+
+			statement = statements.first
+			access = begin
+				Resolver.new(catalog:).analyze(statement)
+			rescue *STACK_EXHAUSTED
+				# As with parsing, how deep the resolver can go depends on the stack the caller has left
+				raise Error, "statement nested too deeply"
+			end
+			raise Error.new(unresolved: access.unresolved) if strict && !access.resolved?
+
+			access
+		end
+
+		# Reads and writes for any number of statements, a migration or a whole log line - with the
+		# same arguments as `access`. Each statement sees the schema as the statements before it left
+		# it: a copy of the catalog is changed as they create, alter and drop things, and the catalog
+		# passed in stays as it was
+		def self.summary(sql, catalog: nil, strict: true)
+			statements = statements(sql)
+			catalog = catalog&.dup
+			accesses = statements.map do |statement|
+				access(statement, catalog:, strict:).tap { catalog&.apply(statement) }
+			end
+			Summary.new(statements, accesses)
+		end
+
+		def self.statements(sql)
+			case sql
+			when Node then [sql]
+			when Array then sql
+			else Parser.new(sql).parse
+			end
+		end
+		private_class_method :statements
+	end
+end

data/lib/plume/ast/alter_table_statement.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Plume
+	# **[SQLite Docs](https://www.sqlite.org/lang_altertable.html)**
+	#
+	# `action` is :RENAME_TABLE, :RENAME_COLUMN, :ADD_COLUMN, :DROP_COLUMN, :ADD_CONSTRAINT (a CHECK),
+	# :DROP_CONSTRAINT, :SET_NOT_NULL or :DROP_NOT_NULL
+	class AlterTableStatement < Node
+		Action = _Union(
+			:RENAME_TABLE, :RENAME_COLUMN, :ADD_COLUMN, :DROP_COLUMN,
+			:ADD_CONSTRAINT, :DROP_CONSTRAINT, :SET_NOT_NULL, :DROP_NOT_NULL,
+		)
+
+		token :alter_table_kw
+		token :action_kw # RENAME [COLUMN], ADD [COLUMN], DROP [COLUMN], DROP CONSTRAINT or ALTER [COLUMN]
+		token :column_tk
+		token :to_kw
+		token :new_name_tk
+		token :constraint_name_tk
+		token :not_null_kw # SET NOT NULL or DROP NOT NULL
+
+		node :table, TableName
+		attribute :action, Action
+		node :column_definition, ColumnDefinition
+		node :constraint, CheckTableConstraint
+		node :conflict_clause, ConflictClause
+		attribute :column, Stringy
+		attribute :new_name, Stringy
+		attribute :constraint_name, Stringy
+
+		def self.new(*, table:, action:, **) = super
+		def self.concrete(*, alter_table_kw:, table:, action:, **) = super
+
+		def action = @action
+		def column = (@column == LiteralNil) ? column_tk_val : @column
+		def new_name = (@new_name == LiteralNil) ? new_name_tk_val : @new_name
+		# The constraint dropped, or added - which keeps its name on `constraint`
+		def constraint_name = (@constraint_name == LiteralNil) ? (constraint_name_tk_val || constraint&.name) : @constraint_name
+	end
+end

data/lib/plume/ast/analyze_statement.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Plume
+	# **[SQLite Docs](https://www.sqlite.org/lang_analyze.html)**
+	#
+	# `target` names a schema, table or index - SQLite works out which at run time
+	class AnalyzeStatement < Node
+		token :analyze_kw
+
+		node :target, TableName
+
+		def self.new(*, **) = super
+		def self.concrete(*, analyze_kw:, **) = super
+	end
+end

data/lib/plume/ast/assignment.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Plume
+	# One `col = expr` or `(a, b) = expr` from a SET list
+	class Assignment < Node
+		token :columns_lp
+		token :columns_rp
+		token :eq_tk
+
+		nodes :columns, ColumnName
+		node :value, Expression
+
+		def self.new(*, columns:, value:, **) = super
+		def self.concrete(*, columns:, value:, **) = super
+
+		def column_names = columns.map(&:column)
+	end
+end

data/lib/plume/ast/attach_statement.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Plume
+	# **[SQLite Docs](https://www.sqlite.org/lang_attach.html)**
+	class AttachStatement < Node
+		token :attach_kw # ATTACH or ATTACH DATABASE
+		token :as_kw
+		token :key_kw
+
+		node :file, Expression
+		node :schema, Expression
+		node :key, Expression
+
+		def self.new(*, file:, schema:, **) = super
+		def self.concrete(*, attach_kw:, file:, schema:, **) = super
+	end
+end

data/lib/plume/ast/begin_statement.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Plume
+	# **[SQLite Docs](https://www.sqlite.org/lang_transaction.html)**
+	class BeginStatement < Node
+		token :begin_kw
+		token :type_kw
+		token :transaction_kw
+		token :name_tk
+
+		def self.new(*, **) = super
+		def self.concrete(*, begin_kw:, **) = super
+
+		# :DEFERRED, :IMMEDIATE, :EXCLUSIVE, or nil for SQLite's default (deferred)
+		inspectable def type = type_kw_tok
+	end
+end

data/lib/plume/ast/binary_expression.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Plume
+	class BinaryExpression < Node
+		TOKEN_TO_OPERATOR = {
+			:AND                                 => :ALL,
+			:OR                                  => :ANY,
+			:CONCAT                              => :CONCAT,
+			:PTR1                                => :EXTRACT,
+			:PTR2                                => :RETRIEVE,
+			:STAR                                => :MULTIPLY,
+			:SLASH                               => :DIVIDE,
+			:REM                                 => :MODULO,
+			:PLUS                                => :ADD,
+			:MINUS                               => :SUB,
+			:BITAND                              => :BIT_AND,
+			:BITOR                               => :BIT_OR,
+			:LSHIFT                              => :BIT_LSHIFT,
+			:RSHIFT                              => :BIT_RSHIFT,
+			:LT                                  => :BELOW,
+			:GT                                  => :ABOVE,
+			:LE                                  => :ATMOST,
+			:GE                                  => :ATLEAST,
+			:EQ                                  => :EQUALS,
+			:NE                                  => :NOT_EQUALS,
+			:IS                                  => :IS,
+			:GLOB                                => :GLOB,
+			:REGEXP                              => :REGEXP,
+			:MATCH                               => :MATCH,
+			:IN                                  => :IN,
+			[:IS, :NOT, :DISTINCT, :FROM].freeze => :IS,
+			[:IS, :DISTINCT, :FROM].freeze       => :IS_NOT,
+			[:IS, :NOT].freeze                   => :IS_NOT,
+			[:IS].freeze                         => :IS,
+			[:GLOB].freeze                       => :GLOB,
+			[:REGEXP].freeze                     => :REGEXP,
+			[:MATCH].freeze                      => :MATCH,
+			[:IN].freeze                         => :IN,
+			[:NOT, :GLOB].freeze                 => :NOT_GLOB,
+			[:NOT, :REGEXP].freeze               => :NOT_REGEXP,
+			[:NOT, :MATCH].freeze                => :NOT_MATCH,
+			[:NOT, :IN].freeze                   => :NOT_IN,
+		}.freeze
+		Operator = _Union(*TOKEN_TO_OPERATOR.values)
+
+		token :operator_tk         # required
+		token :left_tk             # required
+		token :right_tk            # required
+
+		attribute :operator, Operator   # required
+		attribute :left,     Expression # required
+		attribute :right,    Expression # required
+
+		def self.new(*, operator:, left:, right:, **) = super
+		def self.concrete(*, operator_tk:, **) = super
+
+		# Parser may pass either tokens or attributes, so
+		# require none in `concrete` signature but ensure presence here.
+		def after_initialize
+			if @left.nil? && @left_tk.nil?
+				raise ArgumentError.new("missing either: :left, :left_tk")
+			elsif @right.nil? && @right_tk.nil?
+				raise ArgumentError.new("missing either: :right, :right_tk")
+			end
+		end
+
+		def operator = (@operator == LiteralNil) ? TOKEN_TO_OPERATOR[operator_tk_tok] : @operator
+		def left = (@left == LiteralNil) ? left_tk_val : @left
+		def right = (@right == LiteralNil) ? right_tk_val : @right
+	end
+end

data/lib/plume/ast/case_condition.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Plume
+	class CaseCondition < Node
+		token :when_kw
+		token :predicate_tk
+		token :then_kw
+		token :consequence_tk
+
+		attribute :predicate, Expression
+		attribute :consequence, Expression
+
+		def self.new(*, predicate:, consequence:, **) = super
+		def self.concrete(*, when_kw:, then_kw:, **) = super
+
+		# Parser may pass either tokens or attributes, so
+		# require none in `concrete` signature but ensure presence here.
+		def after_initialize
+			if @predicate.nil? && @predicate_tk.nil?
+				raise ArgumentError.new("missing either: :predicate, :predicate_tk")
+			elsif @consequence.nil? && @consequence_tk.nil?
+				raise ArgumentError.new("missing either: :consequence, :consequence_tk")
+			end
+		end
+
+		def predicate = (@predicate == LiteralNil) ? predicate_tk_val : @predicate
+		def consequence = (@consequence == LiteralNil) ? consequence_tk_val : @consequence
+	end
+end

data/lib/plume/ast/case_expression.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Plume
+	class CaseExpression < Node
+		token :case_kw
+		token :predicate_tk
+		token :else_kw
+		token :else_clause_tk
+		token :end_kw
+
+		attribute :predicate, Expression
+		attribute :else_clause, Expression
+
+		nodes :conditions, CaseCondition
+
+		def self.new(*, conditions:, **) = super
+		def self.concrete(*, case_kw:, conditions:, end_kw:, **) = super
+
+		def predicate = (@predicate == LiteralNil) ? predicate_tk_val : @predicate
+		def else_clause = (@else_clause == LiteralNil) ? else_clause_tk_val : @else_clause
+	end
+end

data/lib/plume/ast/cast_expression.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Plume
+	class CastExpression < Node
+		token :cast_kw
+		token :expression_lp
+		token :as_kw
+		token :expression_rp
+
+		node :expression, Expression
+		node :as, ColumnType
+
+		def self.new(*, expression:, as:, **) = super
+		def self.concrete(*, cast_kw:, expression_lp:, expression:, as_kw:, as:, expression_rp:, **) = super
+	end
+end

data/lib/plume/ast/check_column_constraint.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Plume
+	class CheckColumnConstraint < ColumnConstraint
+		token :constraint_kw
+		token :name_tk
+		token :check_kw
+		token :check_lp
+		token :check_rp
+
+		attribute :name, Stringy
+		node :expression, Expression
+		node :conflict_clause, ConflictClause
+
+		def self.new(*, expression:, **) = super
+		def self.concrete(*, check_kw:, check_lp:, expression:, check_rp:, **) = super
+
+		def name = (@name == LiteralNil) ? name_tk_val : @name
+	end
+end

data/lib/plume/ast/check_table_constraint.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Plume
+	class CheckTableConstraint < TableConstraint
+		token :constraint_kw
+		token :name_tk
+		token :check_kw
+		token :check_lp
+		token :check_rp
+
+		attribute :name, Stringy
+		node :expression, Expression
+		node :conflict_clause, ConflictClause
+
+		def self.new(*, expression:, **) = super
+		def self.concrete(*, expression:, **) = super
+
+		def name = (@name == LiteralNil) ? name_tk_val : @name
+	end
+end

data/lib/plume/ast/collate_column_constraint.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Plume
+	class CollateColumnConstraint < ColumnConstraint
+		token :constraint_kw
+		token :name_tk
+		token :collate_kw
+		token :collation_tk
+
+		attribute :name, Stringy
+		attribute :collation, Stringy
+
+		def self.new(*, collation:, **) = super
+		def self.concrete(*, collate_kw:, collation_tk:, **) = super
+
+		def name = (@name == LiteralNil) ? name_tk_val : @name
+		def collation = (@collation == LiteralNil) ? Node.collation_name(collation_tk_val) : @collation
+	end
+end

data/lib/plume/ast/collation_expression.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Plume
+	class CollationExpression < Node
+		token :collate_kw
+		token :expression_tk
+		token :sequence_tk
+
+		attribute :expression, Expression
+		attribute :sequence, Stringy
+
+		def self.new(*, sequence:, **) = super
+		def self.concrete(*, sequence_tk:, **) = super
+
+		# Parser may pass either tokens or attributes, so
+		# require none in `concrete` signature but ensure presence here.
+		def after_initialize
+			if @expression.nil? && @expression_tk.nil?
+				raise ArgumentError.new("missing either: :expression, :expression_tk")
+			end
+		end
+
+		def expression = (@expression == LiteralNil) ? expression_tk_val : @expression
+		def sequence = (@sequence == LiteralNil) ? Node.collation_name(sequence_tk_val) : @sequence
+	end
+end

data/lib/plume/ast/column_constraint.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Plume
+	class ColumnConstraint < Node
+		# abstract
+	end
+end

data/lib/plume/ast/column_definition.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Plume
+	class ColumnDefinition < Node
+		token :name_tk
+
+		attribute :name, Stringy
+		node :type, ColumnType
+		nodes :constraints, ColumnConstraint
+
+		def self.new(*, name:, **) = super
+		def self.concrete(*, name_tk:, **) = super
+
+		def name = (@name == LiteralNil) ? name_tk_val : @name
+	end
+end

data/lib/plume/ast/column_name.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Plume
+	class ColumnName < Node
+		token :schema_tk # maybe
+		token :dot1 # maybe
+		token :table_tk # maybe
+		token :dot2 # maybe
+		token :column_tk # required
+
+		attribute :schema, Stringy # maybe
+		attribute :table, Stringy # maybe
+		attribute :column, Stringy # required
+
+		def self.new(*, column:, **) = super
+		def self.concrete(*, column_tk:, **) = super
+
+		def schema = (@schema == LiteralNil) ? schema_tk_val : @schema
+		def table = (@table == LiteralNil) ? table_tk_val : @table
+		def column = (@column == LiteralNil) ? column_tk_val : @column
+	end
+end

data/lib/plume/ast/column_type.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Plume
+	class ColumnType < Node
+		token :text_span
+
+		attribute :text, Stringy
+
+		def self.new(*, text:, **) = super
+		def self.concrete(*, text_span:, **) = super
+
+		def text = (@text == LiteralNil) ? text_span_val : @text
+
+		inspectable def affinity
+			# rules found at: https://www.sqlite.org/datatype3.html#determination_of_column_affinity
+			# Matched as bytes, as SQLite does, so a type name that is not valid UTF-8 has one too
+			case text&.b
+			when /INT/i							then	:INTEGER
+			when /CHAR|CLOB|TEXT/i	then	:TEXT
+			when /BLOB/i						then	:BLOB
+			when /REAL|FLOA|DOUB/i	then	:REAL
+			else													:ANY
+			end
+		end
+	end
+end

data/lib/plume/ast/commit_statement.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Plume
+	# COMMIT or END. **[SQLite Docs](https://www.sqlite.org/lang_transaction.html)**
+	class CommitStatement < Node
+		token :commit_kw
+		token :transaction_kw
+		token :name_tk
+
+		def self.new(*, **) = super
+		def self.concrete(*, commit_kw:, **) = super
+	end
+end

data/lib/plume/ast/common_table_expression.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Plume
+	class CommonTableExpression < Node
+		token :name_tk
+		token :columns_lp
+		token :columns_rp
+		token :as_kw
+		token :materialized_tk
+		token :select_lp
+		token :select_rp
+
+		attribute :name, Stringy
+		nodes :columns, IndexedColumn
+		node :select, SelectStatement
+
+		def self.new(*, name:, select:, **) = super
+		def self.concrete(*, name_tk:, select:, **) = super
+
+		def name = (@name == LiteralNil) ? name_tk_val : @name
+		def column_names = columns&.map(&:name)
+
+		# true for MATERIALIZED, false for NOT MATERIALIZED, nil when left to the planner
+		inspectable def materialized
+			case materialized_tk_tok
+			when :MATERIALIZED then true
+			when [:NOT, :MATERIALIZED] then false
+			end
+		end
+	end
+end