Description
Describe change in content, appearance, or functionality
I'd like to experiment with a different docs format for hyperfunctions in Toolkit. I'm basing a lot of this off what MDN is and has done in the past.
Here's what the format looks like:
What it does
One or two sentence description of what this function does and should be used for
Examples
Unless part of a tutorial these need to be inline examples that can run on their own using subqueries or generate_series
Also these should be useful solution examples: Here's how you query X to find Y
The syntax section below is for straight up "run the function" examples
ex:
SELECT revenue / toolkit_experimental.days_in_month(month) as daily_rev FROM (SELECT 100 as revenue, '2021-01-01'::date as month) rev;
...Syntax
Code examples of the various ways you can call this function
SELECT toolkit_experimental.days_in_month(now()::timestamptz) -- 31
...Parameters
Function arguments and their definitions
Return value
Any value returned from the function and its format
Exceptions
E 7CFE rrors handled or unhandled by this function
Polyfill
The core code that runs this function and could be used without the extension at all
This is a critical part of the page to provide value to those who aren't or can't use Timescale
CREATE FUNCTION …For example:
What it does
Get the number of days in a month for PostgreSQL. This function returns the exact number of days in any month based on a given a date or timestamp.
Examples
-- coming soonSyntax
SELECT toolkit_experimental.days_in_month('2021-01-01 00:00:00+03'::timestamptz) -- 31
SELECT toolkit_experimental.days_in_month('2021-02-01 00:00:00+03'::timestamptz) -- 28
SELECT toolkit_experimental.days_in_month('2021-01-01'::date) -- 31
SELECT toolkit_experimental.days_in_month('2021-02-01'::date) -- 28
SELECT toolkit_experimental.days_in_month('2021-01-01') -- 31
SELECT toolkit_experimental.days_in_month('2021-02-01') -- 28
SELECT toolkit_experimental.days_in_month('2020-02-01') -- 29
-- works with functions as well
SELECT toolkit_experimental.days_in_month(now()::timestamptz)
SELECT toolkit_experimental.days_in_month(now()::date)
SELECT toolkit_experimental.days_in_month(now())Parameters
| Name | Type | Description |
|---|---|---|
date |
TIMESTAMPTZ |
Timestamp of the month to retrieve the number of days from |
Return value
Returns an integer value for the number of days
Exceptions
Non-date like parameters will return an error. For example passing an integer 2 or non-date string 'yolo' will result in an error.
Polyfill
With this polyfill you would call SELECT days_in_month(now()) without the toolkit_experimental.days_in_month.
CREATE FUNCTION days_in_month(date timestamptz) RETURNS int AS $$
SELECT CAST(EXTRACT('day' FROM ($1 + interval '1 month' - $1)) as INTEGER)
$$ LANGUAGE SQL STRICT IMMUTABLE PARALLEL SAFE; Subject matter expert (SME)
I'll be pulling people in as needed to assist with examples.
Deadline
Not urgent, I'll be working iteratively on this change over the next few weeks.
Any further info
I know this is a change from the existing formats and I am only interested in experimenting with this and maybe 1 other page in this new format. We can revert this page back to the original page if we feel this format doesn't work or the experiment doesn't produce the results we're expecting. I'd like to run this experiment for about 1 quarter.