# File lib/sequel/extensions/pg_json_ops.rb
-487def[](key)
-488ifis_array?(key)
-489super
-490else
-491case@value
-492whenSymbol, SQL::Identifier, SQL::QualifiedIdentifier, JSONBSubscriptOp
-493# Only use subscripts for identifiers. In other cases, switching from
-494# the -> operator to [] for subscripts causes SQL syntax issues. You
-495# only need the [] for subscripting when doing assignment, and
-496# assignment is generally done on identifiers.
-497self.class.new(JSONBSubscriptOp.new(self, key))
-498else
-499super
-500end
-501end
-502end
+576def[](key)
+577ifis_array?(key)
+578super
+579else
+580case@value
+581whenSymbol, SQL::Identifier, SQL::QualifiedIdentifier, JSONBSubscriptOp
+582# Only use subscripts for identifiers. In other cases, switching from
+583# the -> operator to [] for subscripts causes SQL syntax issues. You
+584# only need the [] for subscripting when doing assignment, and
+585# assignment is generally done on identifiers.
+586self.class.new(JSONBSubscriptOp.new(self, key))
+587else
+588super
+589end
+590end
+591end
Returns json_table SQL function expression, querying JSON data and returning the results as a relational view, which can be accessed similarly to a regular SQL table. This accepts a block that is handled in a similar manner to Database#create_table, though it operates differently.
+
+
Table level options:
+
:on_error
+
How to handle errors when evaluating the JSON path expression.
Variables to pass to the JSON path expression. Keys are variable names, values are the values of the variable.
+
+
+
Inside the block, the following methods can be used:
+
ordinality(name)
+
Include a FOR ORDINALITY column, which operates similar to an autoincrementing primary key.
+
column(name, type, opts={})
+
Return a normal column that uses the given type.
+
exists(name, type, opts={})
+
Return a boolean column for whether the JSON path yields any values.
+
nested(path, &block)
+
Extract nested data from the result set at the given path. This block is treated the same as a json_table block, and arbitrary levels of nesting are supported.
+
+
+
The column method supports the following options:
+
:path
+
JSON path to the object (the default is $.NAME, where NAME is the name of the column).
+
:format
+
Set to :json to use FORMAT JSON, when you expect the value to be a valid JSON object.
+
:on_empty, :on_error
+
How to handle case where JSON path evaluation is empty or results in an error. Values supported are:
Inside the block, methods for Ruby class names are also supported, allowing you to use syntax such as:
+
+
json_op.table('$.a') do
+ String:b
+ Integer:c, path:'$.d'
+end
+
+
+
One difference between this method and Database#create_table is that method_missing is not supported inside the block. Use the column method for PostgreSQL types that are not mapped to Ruby classes.
diff --git a/rdoc-plugins/created.rid b/rdoc-plugins/created.rid
index 2cba12ee1..16128deb6 100644
--- a/rdoc-plugins/created.rid
+++ b/rdoc-plugins/created.rid
@@ -1,4 +1,4 @@
-Sun, 01 Sep 2024 09:23:11 -0700
+Tue, 01 Oct 2024 09:00:04 -0700
lib/sequel/extensions/_model_constraint_validations.rb Tue, 24 Jan 2017 12:27:29 -0800
lib/sequel/extensions/_model_pg_row.rb Tue, 11 Oct 2022 13:37:12 -0700
lib/sequel/extensions/_pretty_table.rb Mon, 17 Oct 2022 09:39:14 -0700
@@ -17,6 +17,7 @@ lib/sequel/extensions/constraint_validations.rb Fri, 21 Oct 2022 08:19:04 -0700
lib/sequel/extensions/core_extensions.rb Tue, 01 Aug 2017 08:12:00 -0700
lib/sequel/extensions/core_refinements.rb Mon, 20 Dec 2021 12:57:43 -0800
lib/sequel/extensions/current_datetime_timestamp.rb Tue, 01 Aug 2017 08:12:00 -0700
+lib/sequel/extensions/dataset_run.rb Thu, 05 Sep 2024 15:28:33 -0700
lib/sequel/extensions/dataset_source_alias.rb Thu, 11 Feb 2016 15:50:14 -0800
lib/sequel/extensions/date_arithmetic.rb Fri, 21 Oct 2022 08:19:04 -0700
lib/sequel/extensions/date_parse_input_handler.rb Fri, 17 Dec 2021 16:59:47 -0800
@@ -57,7 +58,7 @@ lib/sequel/extensions/pg_inet.rb Sun, 30 Oct 2022 19:13:54 -0700
lib/sequel/extensions/pg_inet_ops.rb Sat, 18 Dec 2021 12:49:34 -0800
lib/sequel/extensions/pg_interval.rb Sun, 30 Oct 2022 19:13:54 -0700
lib/sequel/extensions/pg_json.rb Sun, 30 Oct 2022 19:13:54 -0700
-lib/sequel/extensions/pg_json_ops.rb Thu, 15 Aug 2024 12:59:16 -0700
+lib/sequel/extensions/pg_json_ops.rb Sun, 29 Sep 2024 11:29:00 -0700
lib/sequel/extensions/pg_loose_count.rb Mon, 24 May 2021 12:25:38 -0700
lib/sequel/extensions/pg_multirange.rb Thu, 13 Apr 2023 12:51:52 -0700
lib/sequel/extensions/pg_range.rb Wed, 06 Dec 2023 16:41:40 -0800
diff --git a/rdoc-plugins/files/lib/sequel/extensions/dataset_run_rb.html b/rdoc-plugins/files/lib/sequel/extensions/dataset_run_rb.html
new file mode 100644
index 000000000..4921d9846
--- /dev/null
+++ b/rdoc-plugins/files/lib/sequel/extensions/dataset_run_rb.html
@@ -0,0 +1,69 @@
+
+
+
+dataset_run.rb
+
+
+
+
+
+
+
+
+
dataset_run.rb
+
+
+lib/sequel/extensions/dataset_run.rb
+
+
+Last Update:
+2024-09-05 15:28:33 -0700
+
+
+
+
+
+
The dataset_run extension is designed for cases where you want to use dataset methods to build a query, but want to run that query without returning a result. The most common need would be to easily use placeholders in an SQL string, which Database#run does not support directly.
+
+
You can load this extension into specific datasets:
+
+
ds = DB["GRANT SELECT ON ? TO ?", :table, :user]
+ds = ds.extension(:dataset_run)
+ds.run
+
+
+
Or you can load it into all of a database’s datasets, which is probably the desired behavior if you are using this extension:
+
+
DB.extension(:dataset_run)
+DB["GRANT SELECT ON ? TO ?", :table, :user].run
+
For the PostgreSQL 12+ SQL/JSON path functions, one argument is required (path) and two more arguments are optional (vars and silent). path specifies the JSON path. vars specifies a hash or a string in JSON format of named variables to be substituted in path. silent specifies whether errors are suppressed. By default, errors are not suppressed.
+
On PostgreSQL 13+ timezone-aware SQL/JSON path functions and operators are supported:
For the PostgreSQL 12+ SQL/JSON path functions, one argument is required (path) and two more arguments are optional (vars and silent). path specifies the JSON path. vars specifies a hash or a string in JSON format of named variables to be substituted in path. silent specifies whether errors are suppressed. By default, errors are not suppressed.
-
On PostgreSQL 14+, The JSONB [] method will use subscripts instead of being the same as get, if the value being wrapped is an identifer:
pg_json_ops.rb
j.is_json(type::object) # j IS JSON OBJECTj.is_json(type::object, unique:true) # j IS JSON OBJECT WITH UNIQUEj.is_not_json# j IS NOT JSON
-j.is_not_json(type::array) # j IS NOT JSON ARRAY
-j.is_not_json(unique:true) # j IS NOT JSON WITH UNIQUE
+j.is_not_json(type::array) # j IS NOT JSON ARRAY
+j.is_not_json(unique:true) # j IS NOT JSON WITH UNIQUE
On PostgreSQL 17+, the additional JSON functions are supported (see method documentation for additional options):
@@ -172,6 +172,29 @@
pg_json_ops.rb
j.exists('$.foo', passing: {a:1}) # json_exists(jsonb_column, '$.foo' PASSING 1 AS a)j.value('$.foo', returning:Time) # json_value(jsonb_column, '$.foo' RETURNING timestamp)j.query('$.foo', wrapper:true) # json_query(jsonb_column, '$.foo' WITH WRAPPER)
+
+j.table('$.foo') do
+ String:bar
+ Integer:baz
+end
+# json_table("jsonb_column", '$.foo' COLUMNS("bar" text, "baz" integer))
+
+j.table('$.foo', passing: {a:1}) do
+ ordinality:id
+ String:bar, format::json, on_error::empty_object
+ nested'$.baz'do
+ Integer:q, path:'$.quux', on_empty::error
+ end
+ exists:x, Date, on_error:false
+end
+# json_table(jsonb_column, '$.foo' PASSING 1 AS a COLUMNS(
+# "id" FOR ORDINALITY,
+# "bar" text FORMAT JSON EMPTY OBJECT ON ERROR,
+# NESTED '$.baz' COLUMNS(
+# "q" integer PATH '$.quux' ERROR ON EMPTY
+# ),
+# "d" date EXISTS FALSE ON ERROR
+# ))
If you are also using the pg_json extension, you should load it before loading this extension. Doing so will allow you to use the op method on JSONHash, JSONHarray, JSONBHash, and JSONBArray, allowing you to perform json/jsonb operations on json/jsonb literals.
+445deflast(*args, &block)
+446raise(Error, 'No order specified') unless@opts[:order]
+447reverse.first(*args, &block)
+448end
@@ -3646,19 +3654,19 @@
Public Instance methods
[show source]
# File lib/sequel/dataset/actions.rb
-456defmap(column=nil, &block)
-457ifcolumn
-458raise(Error, 'Must call Dataset#map with either an argument or a block, not both') ifblock
-459returnnaked.map(column) ifrow_proc
-460ifcolumn.is_a?(Array)
-461super(){|r|r.values_at(*column)}
-462else
-463super(){|r|r[column]}
-464end
-465else
-466super(&block)
-467end
-468end
+464defmap(column=nil, &block)
+465ifcolumn
+466raise(Error, 'Must call Dataset#map with either an argument or a block, not both') ifblock
+467returnnaked.map(column) ifrow_proc
+468ifcolumn.is_a?(Array)
+469super(){|r|r.values_at(*column)}
+470else
+471super(){|r|r[column]}
+472end
+473else
+474super(&block)
+475end
+476end
That way Sequel’s method chaining still works, and it increases Sequel’s ability to introspect the code.
+
If you must work with datasets using custom SQL, and you don’t want to use the implicit_subquery extension, it is recommended you limit yourself to calling the following methods on the dataset:
+
get (without_arguments) or single_value!
+
returns first column value of first row
+
first (without arguments) or single_record!
+
returns first row
+
each
+
yields each row to block
+
all
+
returns all rows
+
map
+
returns array of values
+
to_hash
+
Returns hash mapping given value to row or other values
+
to_hash_groups
+
Returns hash mapping value to array of rows or other values
+
insert
+
For INSERT statements, run the statement (which may or may not return any autoincremented primary key value, depending on adapter used).
+
update, delete
+
For UPDATE or DELETE statements, run the statement and return the number of rows updated or deleted.
+
from_self
+
Wrap the current dataset in a subquery, returning a dataset that can use Sequel’s full dataset API.
+
+
+
Calling other methods, such as methods designed to return a dataset with modified SQL, may result in problems or confusion, since the custom SQL will override the SQL Sequel would normally generate.
The default connection pool on Ruby 3.2+ has switched from threaded to timed_queue. The timed_queue connection pool has been shown to have sufficient advantages over the threaded connection pool to justify the minor backwards compatibility issues (which are documented below). If you would like to continue using the the threaded connection pool, you can use the pool_class: :threaded Database option.
+
+
When calling Dataset#get and first without arguments or blocks, if the receiver already uses raw SQL, no intermediate datasets are created. This improves performance, and fixes an issue with Dataset#get when using the implicit_subquery extension.
The default connection pool switch from threaded to timed_queue can break backwards compatibility if you are accessing the pool directly and using the available_connections or allocated accessor methods. If you are using those methods, or a library that uses them, you’ll need to stop using them, or force the use of the threaded connection pool as described above.