Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jJ6tJ-0002yN-QX for pgsql-hackers@arkaria.postgresql.org; Tue, 31 Mar 2020 02:44:38 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.92) (envelope-from ) id 1jJ6tH-0002n4-CS for pgsql-hackers@arkaria.postgresql.org; Tue, 31 Mar 2020 02:44:35 +0000 Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29]) by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jJ6tG-0002mw-Uz for pgsql-hackers@lists.postgresql.org; Tue, 31 Mar 2020 02:44:35 +0000 Received: from mail-qt1-x844.google.com ([2607:f8b0:4864:20::844]) by magus.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.92) (envelope-from ) id 1jJ6t7-0005H7-1N for pgsql-hackers@postgresql.org; Tue, 31 Mar 2020 02:44:33 +0000 Received: by mail-qt1-x844.google.com with SMTP id x16so17130192qts.11 for ; Mon, 30 Mar 2020 19:44:24 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=telsasoft-com.20150623.gappssmtp.com; s=20150623; h=date:from:to:cc:subject:message-id:references:mime-version :content-disposition:in-reply-to:user-agent; bh=7/7bNWKYY19QORuMyeISFB32pgmlJ0j2aGHgB/OzKLg=; b=Ao46bqlw/Cxk164mNSx5eQoq92gjHeWTWYrOyGf0KWVGNO7lyK3FG0atNf07M9N0Ix d20nSXoESdxrIsudGwZ6f3awY44Xi6vh6nuwKBV22H6QnjUa/iMsPWYldOYuEt5JDQNH Yb7i0ukeSaaSq2IdCNAegNVhZZvmVYu1i9e+XyT7oyFHBIEujvd0Rk8TtbFX4gHCAa0K mivVJb9qaGcLiz92XhmuDrVks/WlXMrkOwZTQXFi6iVk2BT/dSujIv/6UlYsEa+ACsSS 56SBfWA5mbXMuvjK7vEVTRQ6W6oQciiVCrVidtjRM5otgMlDCa4A18iB6uEYalG1Rne+ /+FQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:in-reply-to:user-agent; bh=7/7bNWKYY19QORuMyeISFB32pgmlJ0j2aGHgB/OzKLg=; b=s+4Db9b+ffeI6g0b0TQRDgyOJFeaj/N0w8GVvp/b5O1Z7OFxWMS3fkRAZrgDuQCb+U t/FGqOZQou+ECPVoBts5iDR05YUU5VVfBg+/AG89jxx2mflwMrKLMfCA4IQgP8W5olru qxVJhxYhUxXAUFmFj+0h2isioq077C73UlRtkQMTTU7C0wskIMXUvPB2SrAkABByITNT 7kIa6L9jLViAF0jiY9MnAWeOywuzDQyvhql/TtNkZmKd/sc4p9BZNdQ1ydLTEnDbwZwD 9g5xN/xcyS7kiPQFAqRRkrewj9CTlpaerESbGveoemb0TkpUjUl97ZipilOXh/KsCthn lOhw== X-Gm-Message-State: ANhLgQ3r59yF973800YddQWSQGA6mWYf/BQ5cQFj7fTJWd5dUcsaYz9E XuVOu7zx8FHw/QsKOYf0a0YwVg== X-Google-Smtp-Source: ADFU+vt9qWVgNRBImHwJs4aGzQlrvRG2U7Jcv8sSGAoteGwjFpFBxEIZ8CHAmYZ3mt/iaK8tqT+J2w== X-Received: by 2002:ac8:32db:: with SMTP id a27mr3112285qtb.165.1585622663096; Mon, 30 Mar 2020 19:44:23 -0700 (PDT) Received: from pryzbyj (charmander.telsasoft.com. [50.244.222.1]) by smtp.gmail.com with ESMTPSA id n21sm12962616qtn.17.2020.03.30.19.44.21 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Mon, 30 Mar 2020 19:44:21 -0700 (PDT) Received: by pryzbyj (Postfix, from userid 1000) id CDF27800C2E; Mon, 30 Mar 2020 21:44:19 -0500 (CDT) Date: Mon, 30 Mar 2020 21:44:19 -0500 From: Justin Pryzby To: Alexander Korotkov Cc: Nikita Glukhov , pgsql-hackers@postgresql.org, Tomas Vondra , Alvaro Herrera , Robert Haas , Tom Lane , Nikolay Shaplov , Oleg Bartunov Subject: Re: [PATCH] Opclass parameters Message-ID: <20200331024419.GB14618@telsasoft.com> References: <20190903220254.GA22389@alvherre.pgsql> <20190910220358.6tj37k4v6vyaqac7@development> <0807f67b-c1bd-3760-7fc5-89900ae65408@postgrespro.ru> <20190912001634.oeteg5edzke47om4@development> <5e95f74b-977f-ce98-cd73-302a0fb83e9f@postgrespro.ru> <683fc323-e483-c972-e6bf-d03994a8df67@postgrespro.ru> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="kORqDWCi7qDJ0mEj" Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.9.4 (2018-02-28) List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Precedence: bulk --kORqDWCi7qDJ0mEj Content-Type: text/plain; charset=us-ascii Content-Disposition: inline On Sat, Mar 28, 2020 at 06:05:51PM +0300, Alexander Korotkov wrote: > On Wed, Mar 18, 2020 at 3:28 AM Nikita Glukhov wrote: > > Attached new version of reordered patches. > > I'm going to push this if no objections. Find attached patch with editorial corrections to docs for this commit. --word-diff to follow. commit d3f077b813efa90b25a162bf8d227f3e4218c248 Author: Justin Pryzby Date: Mon Mar 30 20:55:06 2020 -0500 Doc review: Implement operator class parameters commit 911e70207703799605f5a0e8aad9f06cff067c63 Author: Alexander Korotkov diff --git a/doc/src/sgml/hstore.sgml b/doc/src/sgml/hstore.sgml index f1f2b08cd7..b2e04d0815 100644 --- a/doc/src/sgml/hstore.sgml +++ b/doc/src/sgml/hstore.sgml @@ -468,13 +468,13 @@ CREATE INDEX hidx ON testhstore USING GIN (h); gist_hstore_ops GiST opclass approximates {+a+} set of key/value pairs as a bitmap signature. [-Optional-]{+Its optional+} integer parameter siglen[-of gist_hstore_ops-] determines {+the+} signature length in bytes. [-Default signature-]{+The default+} length is 16 bytes. Valid values of signature length are between 1 and 2024 bytes. Longer signatures [-leads-]{+lead+} to {+a+} more precise search [-(scan less-]{+(scanning a smaller+} fraction of [-index, scan-] [- less-]{+the index and+} {+ fewer+} heap pages), [-but-]{+at the cost of a+} larger index. diff --git a/doc/src/sgml/intarray.sgml b/doc/src/sgml/intarray.sgml index 72b4b23c15..7956a746a6 100644 --- a/doc/src/sgml/intarray.sgml +++ b/doc/src/sgml/intarray.sgml @@ -265,7 +265,7 @@ Two [-parametrized-]{+parameterized+} GiST index operator classes are provided: gist__int_ops (used by default) is suitable for small- to medium-size data sets, while gist__intbig_ops uses a larger signature and is more @@ -276,22 +276,23 @@ gist__int_ops approximates {+an+} integer set as an array of integer ranges. [-Optional-]{+Its optional+} integer parameter numranges[-of-] [- gist__int_ops-] determines {+the+} maximum number of ranges in one index key. [-Default-]{+The default+} value of numranges is 100. Valid values are between 1 and 253. Using larger arrays as GiST index keys leads to {+a+} more precise search [-(scan less-]{+(scaning a smaller+} fraction of [-index, scan less-]{+the index and+} {+ fewer+} heap pages), [-but-]{+at the cost of a+} larger index. gist__intbig_ops approximates {+an+} integer set as a bitmap [-signature. Optional-]{+signature XXX. Its optional+} integer parameter siglen[-of-] [- gist__intbig_ops-] determines {+the+} signature length in bytes. [-Default-]{+The default+} signature length is 16 bytes. Valid values of signature length are between 1 and 2024 bytes. Longer signatures [-leads-]{+lead+} to {+a+} more precise search [-(scan less-]{+(scanning a smaller+} fraction of [-index, scan less-]{+the index and fewer+} heap pages), [-but-]{+at+} {+ the cost of a+} larger index. diff --git a/doc/src/sgml/ltree.sgml b/doc/src/sgml/ltree.sgml index ae4b33ec85..4971b71524 100644 --- a/doc/src/sgml/ltree.sgml +++ b/doc/src/sgml/ltree.sgml @@ -506,16 +506,16 @@ Europe & Russia*@ & !Transportation @, ~, ? gist_ltree_ops GiST opclass approximates {+a+} set of path labels as a bitmap signature. [-Optional-]{+Its optional+} integer parameter siglen[-of gist_ltree_ops-] determines {+the+} signature length in bytes. [-Default-]{+The default+} signature length is 8 bytes. Valid values of signature length are between 1 and 2024 bytes. Longer signatures [-leads-]{+lead+} to {+a+} more precise search [-(scan less-]{+(scanning a smaller+} fraction of [-index, scan-] [- less-]{+the index and+} {+ fewer+} heap pages), [-but-]{+at the cost of a+} larger index. Example of creating such an index with [-a-]{+the+} default signature length of 8 bytes: CREATE INDEX path_gist_idx ON test USING GIST (path); @@ -535,13 +535,13 @@ CREATE INDEX path_gist_idx ON test USING GIST (path gist_ltree_ops(siglen=100)); @, ~, ? gist__ltree_ops GiST opclass works [-similar-]{+similarly+} to gist_ltree_ops and also takes signature length as a parameter. [-Default-]{+The default+} value of siglen in gist__ltree_ops is 28 bytes. Example of creating such an index with [-a-]{+the+} default signature length of 28 bytes: CREATE INDEX path_gist_idx ON test USING GIST (array_path); diff --git a/doc/src/sgml/pgtrgm.sgml b/doc/src/sgml/pgtrgm.sgml index dde02634ae..97b3d13a88 100644 --- a/doc/src/sgml/pgtrgm.sgml +++ b/doc/src/sgml/pgtrgm.sgml @@ -391,13 +391,13 @@ CREATE INDEX trgm_idx ON test_trgm USING GIN (t gin_trgm_ops); gist_trgm_ops GiST opclass approximates {+a+} set of trigrams as a bitmap signature. [-Optional-]{+Its optional+} integer parameter siglen[-of gist_trgm_ops-] determines {+the+} signature length in bytes. [-Default signature-]{+The default+} length is 12 bytes. Valid values of signature length are between 1 and 2024 bytes. Longer signatures [-leads-]{+lead+} to {+a+} more precise search [-(scan less-]{+(scanning a smaller+} fraction of [-index, scan-] [- less-]{+the index and+} {+ fewer+} heap pages), [-but-]{+at the cost of a+} larger index. diff --git a/doc/src/sgml/textsearch.sgml b/doc/src/sgml/textsearch.sgml index 2217fcd6c2..0dc427289d 100644 --- a/doc/src/sgml/textsearch.sgml +++ b/doc/src/sgml/textsearch.sgml @@ -3670,17 +3670,17 @@ SELECT plainto_tsquery('supernovae stars'); to check the actual table row to eliminate such false matches. (PostgreSQL does this automatically when needed.) GiST indexes are lossy because each document is represented in the index by a fixed-length signature. [-Signature-]{+The signature+} length in bytes is determined by the value of the optional integer parameter siglen. [-Default-]{+The default+} signature length (when siglen is not [-specied)-]{+specified)+} is 124 bytes, [-maximal-]{+the maximum signature+} length is 2024 bytes. The signature is generated by hashing each word into a single bit in an n-bit string, with all these bits OR-ed together to produce an n-bit document signature. When two words hash to the same bit position there will be a false match. If all words in the query have matches (real or false) then the table row must be retrieved to see if the match is correct. Longer signatures [-leads-]{+lead+} to {+a+} more precise search [-(scan less-]{+(scanning a smaller+} fraction of [-index, scan less-]{+the index and fewer+} heap pages), [-but-]{+at the cost of a+} larger index. --kORqDWCi7qDJ0mEj Content-Type: text/x-diff; charset=us-ascii Content-Disposition: attachment; filename="v1-0001-Doc-review-Implement-operator-class-parameters.patch" From d3f077b813efa90b25a162bf8d227f3e4218c248 Mon Sep 17 00:00:00 2001 From: Justin Pryzby Date: Mon, 30 Mar 2020 20:55:06 -0500 Subject: [PATCH v1] Doc review: Implement operator class parameters commit 911e70207703799605f5a0e8aad9f06cff067c63 Author: Alexander Korotkov --- doc/src/sgml/hstore.sgml | 12 ++++++------ doc/src/sgml/intarray.sgml | 27 ++++++++++++++------------- doc/src/sgml/ltree.sgml | 20 ++++++++++---------- doc/src/sgml/pgtrgm.sgml | 12 ++++++------ doc/src/sgml/textsearch.sgml | 12 ++++++------ 5 files changed, 42 insertions(+), 41 deletions(-) diff --git a/doc/src/sgml/hstore.sgml b/doc/src/sgml/hstore.sgml index f1f2b08cd7..b2e04d0815 100644 --- a/doc/src/sgml/hstore.sgml +++ b/doc/src/sgml/hstore.sgml @@ -468,13 +468,13 @@ CREATE INDEX hidx ON testhstore USING GIN (h); - gist_hstore_ops GiST opclass approximates set of - key/value pairs as a bitmap signature. Optional integer parameter - siglen of gist_hstore_ops determines - signature length in bytes. Default signature length is 16 bytes. + gist_hstore_ops GiST opclass approximates a set of + key/value pairs as a bitmap signature. Its optional integer parameter + siglen determines the + signature length in bytes. The default length is 16 bytes. Valid values of signature length are between 1 and 2024 bytes. Longer - signatures leads to more precise search (scan less fraction of index, scan - less heap pages), but larger index. + signatures lead to a more precise search (scanning a smaller fraction of the index and + fewer heap pages), at the cost of a larger index. diff --git a/doc/src/sgml/intarray.sgml b/doc/src/sgml/intarray.sgml index 72b4b23c15..7956a746a6 100644 --- a/doc/src/sgml/intarray.sgml +++ b/doc/src/sgml/intarray.sgml @@ -265,7 +265,7 @@ - Two parametrized GiST index operator classes are provided: + Two parameterized GiST index operator classes are provided: gist__int_ops (used by default) is suitable for small- to medium-size data sets, while gist__intbig_ops uses a larger signature and is more @@ -276,22 +276,23 @@ - gist__int_ops approximates integer set as an array of - integer ranges. Optional integer parameter numranges of - gist__int_ops determines maximum number of ranges in - one index key. Default value of numranges is 100. + gist__int_ops approximates an integer set as an array of + integer ranges. Its optional integer parameter numranges + determines the maximum number of ranges in + one index key. The default value of numranges is 100. Valid values are between 1 and 253. Using larger arrays as GiST index - keys leads to more precise search (scan less fraction of index, scan less - heap pages), but larger index. + keys leads to a more precise search (scaning a smaller fraction of the index and + fewer heap pages), at the cost of a larger index. - gist__intbig_ops approximates integer set as a bitmap - signature. Optional integer parameter siglen of - gist__intbig_ops determines signature length in bytes. - Default signature length is 16 bytes. Valid values of signature length - are between 1 and 2024 bytes. Longer signatures leads to more precise - search (scan less fraction of index, scan less heap pages), but larger index. + gist__intbig_ops approximates an integer set as a bitmap + signature XXX. Its optional integer parameter siglen + determines the signature length in bytes. + The default signature length is 16 bytes. Valid values of signature length + are between 1 and 2024 bytes. Longer signatures lead to a more precise + search (scanning a smaller fraction of the index and fewer heap pages), at + the cost of a larger index. diff --git a/doc/src/sgml/ltree.sgml b/doc/src/sgml/ltree.sgml index ae4b33ec85..4971b71524 100644 --- a/doc/src/sgml/ltree.sgml +++ b/doc/src/sgml/ltree.sgml @@ -506,16 +506,16 @@ Europe & Russia*@ & !Transportation @, ~, ? - gist_ltree_ops GiST opclass approximates set of - path labels as a bitmap signature. Optional integer parameter - siglen of gist_ltree_ops determines - signature length in bytes. Default signature length is 8 bytes. + gist_ltree_ops GiST opclass approximates a set of + path labels as a bitmap signature. Its optional integer parameter + siglen determines the + signature length in bytes. The default signature length is 8 bytes. Valid values of signature length are between 1 and 2024 bytes. Longer - signatures leads to more precise search (scan less fraction of index, scan - less heap pages), but larger index. + signatures lead to a more precise search (scanning a smaller fraction of the index and + fewer heap pages), at the cost of a larger index. - Example of creating such an index with a default signature length of 8 bytes: + Example of creating such an index with the default signature length of 8 bytes: CREATE INDEX path_gist_idx ON test USING GIST (path); @@ -535,13 +535,13 @@ CREATE INDEX path_gist_idx ON test USING GIST (path gist_ltree_ops(siglen=100)); @, ~, ? - gist__ltree_ops GiST opclass works similar to + gist__ltree_ops GiST opclass works similarly to gist_ltree_ops and also takes signature length as - a parameter. Default value of siglen in + a parameter. The default value of siglen in gist__ltree_ops is 28 bytes. - Example of creating such an index with a default signature length of 28 bytes: + Example of creating such an index with the default signature length of 28 bytes: CREATE INDEX path_gist_idx ON test USING GIST (array_path); diff --git a/doc/src/sgml/pgtrgm.sgml b/doc/src/sgml/pgtrgm.sgml index dde02634ae..97b3d13a88 100644 --- a/doc/src/sgml/pgtrgm.sgml +++ b/doc/src/sgml/pgtrgm.sgml @@ -391,13 +391,13 @@ CREATE INDEX trgm_idx ON test_trgm USING GIN (t gin_trgm_ops); - gist_trgm_ops GiST opclass approximates set of - trigrams as a bitmap signature. Optional integer parameter - siglen of gist_trgm_ops determines - signature length in bytes. Default signature length is 12 bytes. + gist_trgm_ops GiST opclass approximates a set of + trigrams as a bitmap signature. Its optional integer parameter + siglen determines the + signature length in bytes. The default length is 12 bytes. Valid values of signature length are between 1 and 2024 bytes. Longer - signatures leads to more precise search (scan less fraction of index, scan - less heap pages), but larger index. + signatures lead to a more precise search (scanning a smaller fraction of the index and + fewer heap pages), at the cost of a larger index. diff --git a/doc/src/sgml/textsearch.sgml b/doc/src/sgml/textsearch.sgml index 2217fcd6c2..0dc427289d 100644 --- a/doc/src/sgml/textsearch.sgml +++ b/doc/src/sgml/textsearch.sgml @@ -3670,17 +3670,17 @@ SELECT plainto_tsquery('supernovae stars'); to check the actual table row to eliminate such false matches. (PostgreSQL does this automatically when needed.) GiST indexes are lossy because each document is represented in the - index by a fixed-length signature. Signature length in bytes is determined + index by a fixed-length signature. The signature length in bytes is determined by the value of the optional integer parameter siglen. - Default signature length (when siglen is not specied) is - 124 bytes, maximal length is 2024 bytes. The signature is generated by hashing + The default signature length (when siglen is not specified) is + 124 bytes, the maximum signature length is 2024 bytes. The signature is generated by hashing each word into a single bit in an n-bit string, with all these bits OR-ed together to produce an n-bit document signature. When two words hash to the same bit position there will be a false match. If all words in the query have matches (real or false) then the table row must be - retrieved to see if the match is correct. Longer signatures leads to more - precise search (scan less fraction of index, scan less heap pages), but - larger index. + retrieved to see if the match is correct. Longer signatures lead to a more + precise search (scanning a smaller fraction of the index and fewer heap + pages), at the cost of a larger index. -- 2.17.0 --kORqDWCi7qDJ0mEj--