Re: SQL/JSON revisited
Hi,
The Postgres Pro documentation team prepared another SQL/JSON
documentation patch (attached), to apply on top of
v1-0009-Documentation-for-SQL-JSON-features.patch.
The new patch:
- Fixes minor typos
- Does some rewording agreed with Nikita Glukhov
- Updates Docbook markup to make tags consistent across SQL/JSON
documentation and across func.sgml, and in particular, consistent with
the XMLTABLE function, which resembles SQL/JSON functions pretty much.
--
Elena Indrupskaya
Lead Technical Writer
Postgres Professional http://www.postgrespro.com
On 28.12.2022 10:28, Amit Langote wrote:
Hi,
Rebased the SQL/JSON patches over the latest HEAD. I've decided to
keep the same division of code into individual commits as that
mentioned in the revert commit 2f2b18bd3f, squashing fixup commits in
that list into the appropriate feature commits.
The main difference from the patches as they were committed into v15
is that JsonExpr evaluation no longer needs to use sub-transactions,
thanks to the work done recently to handle type errors softly. I've
made the new code pass an ErrorSaveContext into the type-conversion
related functions as needed and also added an ExecEvalExprSafe() to
evaluate sub-expressions of JsonExpr that might contain expressions
that call type-conversion functions, such as CoerceViaIO contained in
JsonCoercion nodes. ExecExprEvalSafe() is based on one of the patches
that Nikita Glukhov had submitted in a previous discussion about
redesigning SQL/JSON expression evaluation [1]. Though, I think that
new interface will become unnecessary after I have finished rebasing
my patches to remove subsidiary ExprStates of JsonExprState that we
had also discussed back in [2].
Adding this to January CF.
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index cc72b9c2f6d..8614a26fe95 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -17675,18 +17675,18 @@ $.* ? (@ like_regex "^\\d+$")
json constructor
json (
- expression
+ expression
FORMAT JSON ENCODING UTF8
{ WITH | WITHOUT } UNIQUE KEYS
RETURNING json_data_type )
-The expression can be any text type or a
+The expression can be any text type or a
bytea in UTF8 encoding. If the
-expression is NULL, an
+expression is NULL, an
SQL null value is returned.
If WITH UNIQUE is specified, the
-expression must not contain any duplicate
+expression must not contain any duplicate
object keys.
@@ -17701,12 +17701,12 @@ $.* ? (@ like_regex "^\\d+$")
json_scalar
-json_scalar (expression
+json_scalar (expression
RETURNING json_data_type )
Returns a JSON scalar value representing
-expression.
+expression.
If the input is NULL, an SQL NULL is returned. If the input is a number
or a boolean value, a corresponding JSON number or boolean value is
returned. For any other value a JSON string is returned.
@@ -17724,8 +17724,8 @@ $.* ? (@ like_regex "^\\d+$")
json_object
json_object (
- { key_expression { VALUE | ':' }
- value_expression FORMAT JSON ENCODING UTF8 }, ...
+ { key_expression { VALUE | ':' }
+ value_expression FORMAT JSON ENCODING UTF8 }, ...
{ NULL | ABSENT } ON NULL
{ WITH | WITHOUT } UNIQUE KEYS
RETURNING data_type FORMAT JSON ENCODING UTF8 )
@@ -17733,15 +17733,15 @@ $.* ? (@ like_regex "^\\d+$")
Constructs a JSON object of all the key value pairs given,
or an empty object if none are given.
-key_expression is a scalar expression
+key_expression is a scalar expression
defining the JSON key, which is
converted to the text type.
It cannot be NULL nor can it
belong to a type that has a cast to the json.
If WITH UNIQUE is specified, there must not
-be any duplicate key_expression.
+be any duplicate key_expression.
If ABSENT ON NULL is specified, the entire
-pair is omitted if the value_expression
+pair is omitted if the value_expression
is NULL.
@@ -17753,7 +17753,7 @@ $.* ? (@ like_regex "^\\d+$")
json_objectagg
json_objectagg (
- { key_expression { VALUE | ':' } value_expression }
+ { key_expression { VALUE | ':' } value_expression }
{ NULL | ABSENT } ON NULL
{ WITH | WITHOUT } UNIQUE KEYS
RETURNING data_type FORMAT JSON ENCODING UTF8 )
@@ -17761,8 +17761,8 @@ $.* ? (@ like_regex "^\\d+$")
Behaves like json_object above, but as an
Re: SQL/JSON revisited
Tags in the patch follow the markup of the XMLTABLE function:
XMLTABLE (
XMLNAMESPACES (
namespace_uri AS
namespace_name , ... ),
row_expression
PASSING BY
{REF|VALUE}
document_expression
BY
{REF|VALUE}
COLUMNS name {
type PATH
column_expression
DEFAULT
default_expression
NOT NULL | NULL
| FOR ORDINALITY }
, ...
) setof record
In the above, as well as in the signatures of SQL/JSON functions, there
are no exact parameter names; otherwise, they should have been followed
by the tag, which is not the case. There are no parameter names
in the functions' code either. Therefore, tags seem more
appropriate, according to the comment to commit 47046763c3.
Sorry for upsetting your bot. :(
--
Elena Indrupskaya
Lead Technical Writer
Postgres Professional http://www.postgrespro.com
On 2023-01-10 Tu 07:51, Elena Indrupskaya wrote:
Hi,
The Postgres Pro documentation team prepared another SQL/JSON
documentation patch (attached), to apply on top of
v1-0009-Documentation-for-SQL-JSON-features.patch.
The new patch:
- Fixes minor typos
- Does some rewording agreed with Nikita Glukhov
- Updates Docbook markup to make tags consistent across SQL/JSON
documentation and across func.sgml, and in particular, consistent with
the XMLTABLE function, which resembles SQL/JSON functions pretty much.
That's nice, but please don't post incremental patches like this. It
upsets the cfbot. (I wish there were a way to tell the cfbot to ignore
patches)
Also, I'm fairly certain that a good many of your changes are not
according to project style. The rule as I understand it is that
is used for things that are parameters and is
only used for things that are not parameters. (I'm not sure where that's
documented other than the comment on commit 47046763c3, but it's what I
attempted to do with the earlier doc tidy up.)
cheers
andrew
--
Andrew Dunstan
EDB: https://www.enterprisedb.com
Re: First draft of PG 17 release notes
Hi everybody, Being a technical writer, I attached a small patch that fixes minor language stuff. Thank you. Elena Indrupskaya Postgres Professional Company Moscow, Russia On 09.05.2024 07:03, Bruce Momjian wrote: I have committed the first draft of the PG 17 release notes; you can see the results here: https://momjian.us/pgsql_docs/release-17.html It will be improved until the final release. The item count is 188, which is similar to recent releases: release-10: 189 release-11: 170 release-12: 180 release-13: 178 release-14: 220 release-15: 184 release-16: 206 release-17: 188 I welcome feedback. For some reason it was an easier job than usual. diff --git a/doc/src/sgml/release-17.sgml b/doc/src/sgml/release-17.sgml index 5a741ff16f..1ecf40fc73 100644 --- a/doc/src/sgml/release-17.sgml +++ b/doc/src/sgml/release-17.sgml @@ -73,7 +73,7 @@ Author: Michael Paquier -Restrict "ago" to only appear at the end of in interval values (Joseph Koshakow) +Restrict "ago" to only appear at the end in interval values (Joseph Koshakow) @@ -456,7 +456,7 @@ Author: Tomas Vondra -Allow a BRIN indexes to be created using parallel workers (Tomas Vondra, Matthias van de Meent) +Allow BRIN indexes to be created using parallel workers (Tomas Vondra, Matthias van de Meent) @@ -941,7 +941,7 @@ Allow the creation of WAL summarization files (Robert Haas, Nathan Bossart, Hube -These files record the block numbers that have changed within an LSN range, and is useful for incremental file system backups. This is controlled by the server variables +These files record the block numbers that have changed within an LSN range and are useful for incremental file system backups. This is controlled by the server variables summarize_wal and wal_summarize_keep_time, and introspected with pg_available_wal_summaries(), pg_wal_summary_contents(), and pg_get_wal_summarizer_state(). @@ -1113,7 +1113,7 @@ Allow the application of logical replication changes to use hash indexes on the -Previously only btree indexes could be use for this purpose. +Previously only btree indexes could be used for this purpose. @@ -2185,7 +2185,7 @@ Allow pg_basebackup and pg_receivewal to use dbname in their connection specific -This is useful for connection poolers who are sensitive to the database name. +This is useful for connection poolers that are sensitive to the database name. @@ -2346,7 +2346,7 @@ Author: Michael Paquier -Remove the Microsoft Visual Studio Studio-specific Postgres build option (Michael Paquier) +Remove the Microsoft Visual Studio-specific Postgres build option (Michael Paquier)
