From 4e0092cd7be187eb7dd87617ff71f079253dad57 Mon Sep 17 00:00:00 2001 From: dannykng Date: Thu, 2 Feb 2023 15:42:13 -0800 Subject: [PATCH] Copy edits --- .../guides/database/extensions/hypopg.mdx | 50 +++++++------------ .../database/extensions/pg_jsonschema.mdx | 16 +++--- .../extensions/pg_stat_statements.mdx | 44 +++++++--------- .../guides/database/extensions/pgroonga.mdx | 28 ++++------- 4 files changed, 54 insertions(+), 84 deletions(-) diff --git a/apps/docs/pages/guides/database/extensions/hypopg.mdx b/apps/docs/pages/guides/database/extensions/hypopg.mdx index 6dc5bb3a3ca..cfedd145e07 100644 --- a/apps/docs/pages/guides/database/extensions/hypopg.mdx +++ b/apps/docs/pages/guides/database/extensions/hypopg.mdx @@ -6,11 +6,7 @@ export const meta = { description: 'Quickly check if an index can be used without creating it.', } -`HypoPG` is PostgreSQL extension for creating hypothetical/virtual indexes. - -## Overview - -HypoPG allows users to rapidly create hypothetical/virtual indexes that have no resource cost (CPU, disk, memory) that are visible to the PostgreSQL query planner. +`HypoPG` is PostgreSQL extension for creating hypothetical/virtual indexes. HypoPG allows users to rapidly create hypothetical/virtual indexes that have no resource cost (CPU, disk, memory) that are visible to the PostgreSQL query planner. That allows users to quickly search for an index to improve a slow query without waiting for them to build. ## Usage @@ -48,9 +44,9 @@ It's good practice to create the extension within a separate schema (like `exten -### Speeding up a Query +### Speeding up a query -Given a table populated with some data and simple query to select from the table by id +Given the following table and a simple query to select from the table by id: ```sql create table account ( @@ -66,17 +62,11 @@ from generate_series(1, 10000) id; ``` -we can generate an explain plan for a description of how the PostgreSQL query planner -intends to execute the query. +We can generate an explain plan for a description of how the PostgreSQL query planner +intends to execute the query. ```sql -explain -select - * -from - account -where - id = 1; +explain select * from account where id=1; QUERY PLAN ------------------------------------------------------- @@ -85,14 +75,15 @@ where (2 rows) ``` -Using HypoPG, we can create a hypothetical index on the `account(id)` column to check if it would be useful to the query planner and then re-run the explain plan. +Using HypoPG, we can create a hypothetical index on the `account(id)` column to check if it would be useful to the query planner and then re-run the explain plan. -Note that the virtual indexes created by HypoPG are only visible in the PostgreSQL connection that they were created in. Supabase Studio connects to PostgreSQL through a connection pooler so the `hypopg_create_index` statement and the `explain` statement should be executed in a single query. +Note that the virtual indexes created by HypoPG are only visible in the PostgreSQL connection that they were created in. Supabase connects to PostgreSQL through a connection pooler so the `hypopg_create_index` statement and the `explain` statement should be executed in a single query. ```sql select * from hypopg_create_index('create index on account(id)'); explain select * from account where id=1; + QUERY PLAN ------------------------------------------------------------------------------------ Index Scan using <13504>btree_account_id on hypo (cost=0.29..8.30 rows=1 width=13) @@ -100,28 +91,25 @@ explain select * from account where id=1; (2 rows) ``` -The query plan has changed from a `Seq Scan` to an `Index Scan` using the newly created virtual index, so we may choose to create a real version of the index with: +The query plan has changed from a `Seq Scan` to an `Index Scan` using the newly created virtual index, so we may choose to create a real version of the index to improve performance on the target query: ```sql create index on account(id); ``` -to improve performance on the target query. +## Functions - -API: - -- [`hypo_create_index(text)`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#create-a-hypothetical-index): A function to create a hypothetical index -- [`hypopg_list_indexes`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#manipulate-hypothetical-indexes): A View that lists all hypothetical indexes that have been created -- [`hypopg()`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#manipulate-hypothetical-indexes): A function that lists all hypothetical indexes that have been created with the same format as pg_index -- [`hypopg_get_index_def(oid)`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#manipulate-hypothetical-indexes): A function to display the `create index` statement that would create the index -- [`hypopg_get_relation_size(oid)`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#manipulate-hypothetical-indexes): A function to estimate how large a hypothetical index would be -- [`hypopg_drop_index(oid)`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#manipulate-hypothetical-indexes): A function to remove a given hypothetical index by oid -- [`hypopg_reset()`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#manipulate-hypothetical-indexes): A function to remove all hypothetical indexes +- [`hypo_create_index(text)`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#create-a-hypothetical-index): A function to create a hypothetical index. +- [`hypopg_list_indexes`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#manipulate-hypothetical-indexes): A View that lists all hypothetical indexes that have been created. +- [`hypopg()`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#manipulate-hypothetical-indexes): A function that lists all hypothetical indexes that have been created with the same format as pg_index. +- [`hypopg_get_index_def(oid)`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#manipulate-hypothetical-indexes): A function to display the `create index` statement that would create the index. +- [`hypopg_get_relation_size(oid)`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#manipulate-hypothetical-indexes): A function to estimate how large a hypothetical index would be. +- [`hypopg_drop_index(oid)`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#manipulate-hypothetical-indexes): A function to remove a given hypothetical index by oid. +- [`hypopg_reset()`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#manipulate-hypothetical-indexes): A function to remove all hypothetical indexes. ## Resources -- Official [`HypoPG` documentation](https://hypopg.readthedocs.io/en/rel1_stable/) +- Official [HypoPG documentation](https://hypopg.readthedocs.io/en/rel1_stable/) export const Page = ({ children }) => diff --git a/apps/docs/pages/guides/database/extensions/pg_jsonschema.mdx b/apps/docs/pages/guides/database/extensions/pg_jsonschema.mdx index bfe71f75a46..2f4776afea2 100644 --- a/apps/docs/pages/guides/database/extensions/pg_jsonschema.mdx +++ b/apps/docs/pages/guides/database/extensions/pg_jsonschema.mdx @@ -6,11 +6,7 @@ export const meta = { description: 'Validate json/jsonb with JSON Schema in PostgreSQL.', } -[`pg_jsonschema`](https://json-schema.org) is a PostgreSQL extension adding support for JSON schema validation on json and jsonb data types. - -## Overview - -[JSON Schema](https://json-schema.org) is a language for annotating and validating JSON documents. `pg_jsonschema` adds the ability to validate PostgreSQL's builtin `json` and `jsonb` data types against a JSON Schema document. +[JSON Schema](https://json-schema.org) is a language for annotating and validating JSON documents. [`pg_jsonschema`](https://json-schema.org) is a PostgreSQL extension that adds the ability to validate PostgreSQL's built-in `json` and `jsonb` data types against a JSON Schema document. ## Usage @@ -47,14 +43,14 @@ It's good practice to create the extension within a separate schema (like `exten -API: +## Functions -- [`json_matches_schema(schema json, instance json)`](https://github.com/supabase/pg_jsonschema#api): Checks if a `json` *instance* conforms to a JSON Schema *schema*. -- [`jsonb_matches_schema(schema json, instance jsonb)`](https://github.com/supabase/pg_jsonschema#api): Checks if a `jsonb` *instance* conforms to a JSON Schema *schema*. +- [`json_matches_schema(schema json, instance json)`](https://github.com/supabase/pg_jsonschema#api): Checks if a `json` _instance_ conforms to a JSON Schema _schema_. +- [`jsonb_matches_schema(schema json, instance jsonb)`](https://github.com/supabase/pg_jsonschema#api): Checks if a `jsonb` _instance_ conforms to a JSON Schema _schema_. -### Validating a Document +### Validating a document -Since `pg_jsonschema` exposes its utilities as functions, we can test it with a simple select statement +Since `pg_jsonschema` exposes its utilities as functions, we can test it with a simple select statement: ```sql select diff --git a/apps/docs/pages/guides/database/extensions/pg_stat_statements.mdx b/apps/docs/pages/guides/database/extensions/pg_stat_statements.mdx index a8831f44b81..48e9e757f28 100644 --- a/apps/docs/pages/guides/database/extensions/pg_stat_statements.mdx +++ b/apps/docs/pages/guides/database/extensions/pg_stat_statements.mdx @@ -3,32 +3,24 @@ import Layout from '~/layouts/DefaultGuideLayout' export const meta = { id: 'pg_stat_statements', title: 'pg_stat_statements: SQL Planning and Execution Statistics', - description: 'Track planning and execution statistics of all SQL statements executed on the database.', + description: + 'Track planning and execution statistics of all SQL statements executed on the database.', } -`pg_stat_statements` is a database extension for tracking planning and execution statistics about all SQL statements executed on the database. +`pg_stat_statements` is a database extension that exposes a view, of the same name, to track statistics about SQL statements executed on the database. The following table shows some of the available statistics and metadata: -## Overview - -`pg_stat_statements` exposes a view, of the same name, that tracks statistics about SQL statements executed on the database. The following table shows some of the available statistics and metadata: - -```markdown - -| Column Type | Description | -|-------------|-------------| -| userid oid (references pg_authid.oid) | OID of user who executed the statement | -| dbid oid (references pg_database.oid) | OID of database in which the statement was executed | -| toplevel bool | True if the query was executed as a top-level statement (always true if pg_stat_statements.track is set to top) | -| queryid bigint | Hash code to identify identical normalized queries. | -| query text | Text of a representative statement | -| plans bigint | Number of times the statement was planned (if pg_stat_statements.track_planning is enabled, otherwise zero) | -| total_plan_time double precision -| Total time spent planning the statement, in milliseconds (if pg_stat_statements.track_planning is enabled, otherwise zero) | -| min_plan_time double precision | Minimum time spent planning the statement, in milliseconds (if pg_stat_statements.track_planning is enabled, otherwise zero) | -| ... | ... | -``` -A full list of statistics is available in the [`pg_stat_statements` docs](https://www.postgresql.org/docs/current/pgstatstatements.html) +| Column Type | Description | +| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| userid oid (references pg_authid.oid) | OID of user who executed the statement | +| dbid oid (references pg_database.oid) | OID of database in which the statement was executed | +| toplevel bool | True if the query was executed as a top-level statement (always true if pg_stat_statements.track is set to top) | +| queryid bigint | Hash code to identify identical normalized queries. | +| query text | Text of a representative statement | +| plans bigint | Number of times the statement was planned (if pg_stat_statements.track_planning is enabled, otherwise zero) | +| total_plan_time double precision | Total time spent planning the statement, in milliseconds (if pg_stat_statements.track_planning is enabled, otherwise zero) | +| min_plan_time double precision | Minimum time spent planning the statement, in milliseconds (if pg_stat_statements.track_planning is enabled, otherwise zero) | +A full list of statistics is available in the [pg_stat_statements docs](https://www.postgresql.org/docs/current/pgstatstatements.html). ## Usage @@ -65,9 +57,9 @@ It's good practice to create the extension within a separate schema (like `exten -### Inspecting Activity +### Inspecting activity -A common use for `pg_stat_statements` is to track down expensive or slow queries. The `pg_stat_statements` view contains a row for each executed query with statistics inlined. You can leverage the statistics to, for example, identify frequently executed and slow queries against a given table +A common use for `pg_stat_statements` is to track down expensive or slow queries. The `pg_stat_statements` view contains a row for each executed query with statistics inlined. For example, you can leverage the statistics to identify frequently executed and slow queries against a given table. ```sql select @@ -88,11 +80,11 @@ order by calls desc ``` -From the results, an informed decision about which queries to optimize/index/adjust can be made. +From the results, an informed decision about which queries to optimize, index, or adjust can be made. ## Resources -- Official [`pg_stat_statements` documentation](https://www.postgresql.org/docs/current/pgstatstatements.html) +- Official [pg_stat_statements documentation](https://www.postgresql.org/docs/current/pgstatstatements.html) export const Page = ({ children }) => diff --git a/apps/docs/pages/guides/database/extensions/pgroonga.mdx b/apps/docs/pages/guides/database/extensions/pgroonga.mdx index 0b8b480bf08..858101ef2b7 100644 --- a/apps/docs/pages/guides/database/extensions/pgroonga.mdx +++ b/apps/docs/pages/guides/database/extensions/pgroonga.mdx @@ -43,9 +43,9 @@ It's good practice to create the extension within a separate schema (like `exten -### Creating a Full Text Search Index +### Creating a full text search index -Given a table with a `text` column +Given a table with a `text` column: ```sql create table memos ( @@ -54,7 +54,7 @@ create table memos ( ); ``` -We can index the column for full text search with a `pgroonga` index +We can index the column for full text search with a `pgroonga` index: ```sql create index ix_memos_content ON memos USING pgroonga(content); @@ -71,23 +71,17 @@ values ('There is groonga command.'); ``` -The PostgreSQL query planner is smart enough to know that, for extremely small tables, its faster to scan the whole table rather than loading an index. To force the index to be used, we can disable sequential scans +The PostgreSQL query planner is smart enough to know that, for extremely small tables, it's faster to scan the whole table rather than loading an index. To force the index to be used, we can disable sequential scans: ```sql -- For testing only. Don't do this in production set enable_seqscan = off; ``` -Now if we run an explain plan on a query filtering on `memos.content`, +Now if we run an explain plan on a query filtering on `memos.content`: ```sql -explain -select - * -from - memos -where - content like '%engine%'; +explain select * from memos where content like '%engine%'; QUERY PLAN ----------------------------------------------------------------------------- @@ -96,17 +90,17 @@ Index Scan using ix_memos_content on memos (cost=0.00..1.11 rows=1 width=36) (2 rows) ``` -The pgroonga index is used to retrive the result set +The pgroonga index is used to retrive the result set: ```markdown -| id | content | -| -- | ------------------------------------------------------------------------ | -| 2 | 'Groonga is a fast full text search engine that supports all languages.' | +| id | content | +| --- | ------------------------------------------------------------------------ | +| 2 | 'Groonga is a fast full text search engine that supports all languages.' | ``` ## Resources -- Official [`PGroonga` documentation](https://pgroonga.github.io/tutorial/) +- Official [PGroonga documentation](https://pgroonga.github.io/tutorial/) export const Page = ({ children }) =>