Document the functional API

timescale · Apr 28, 2020 · b23f65c · b23f65c
1 parent 5aaa4c9
commit b23f65c
Show file tree

Hide file tree

Showing 2 changed files with 45 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -45,6 +45,8 @@ interested in a replicated setup for high-availabilty with automated backups, pl
 
 We describe how to use our pre-defined views and functions to work with the prometheus data in [the SQL schema doc](docs/sql_schema.md).
 
+A Reference for our SQL API is [available here](docs/sql_api.md).
+
 # Advanced
 
 ## Helm (sub)chart for Timescale-Prometheus Connector only

diff --git a/docs/sql_api.md b/docs/sql_api.md
@@ -0,0 +1,43 @@
+# Function API Reference
+
+This page is a reference for the functions available in timescale-prometheus.
+
+A description of the usage of these functions, and examples can be found in
+[our description of the sql schema](sql_schema.md)
+
+<!--
+SQL To generate
+
+SELECT
+  p.proname as "Name",
+  pg_catalog.pg_get_function_arguments(p.oid) as "Argument data types",
+  pg_catalog.pg_get_function_result(p.oid) as "Result data type",
+  p.proname || ' ' || pg_catalog.obj_description(p.oid, 'pg_proc') || '.' as "Description"
+FROM pg_catalog.pg_proc p
+     LEFT JOIN pg_catalog.pg_namespace n ON n.oid = p.pronamespace
+     LEFT JOIN pg_catalog.pg_language l ON l.oid = p.prolang
+WHERE n.nspname OPERATOR(pg_catalog.~) '^(prom)$' COLLATE pg_catalog.default
+ORDER BY 1, 2, 4;
+-->
+
+ Name | Arguments | Return type | Description
+ --- | --- | --- | ---
+ drop_chunks                   |                                                          |                  | drop_chunks drops data according to the data retention policy. This procedure should be run regularly in a cron job.
+ eq                            | labels label_array, json_labels jsonb                    | boolean          | eq returns true if the labels and jsonb are equal, ignoring the metric name.
+ eq                            | labels1 label_array, labels2 label_array                 | boolean          | eq returns true if two label arrays are equal, ignoring the metric name.
+ eq                            | labels1 label_array, matchers matcher_positive           | boolean          | eq returns true if the label array and matchers are equal, there should not be a matcher for the metric name.
+ is_normal_nan                 | value double precision                                   | boolean          | is_normal_nan returns true if the value is a NaN.
+ is_stale_marker               | value double precision                                   | boolean          | is_stale_marker returns true if the value is a Prometheus stale marker.
+ jsonb                         | labels label_array                                       | jsonb            | jsonb converts a labels array to a JSONB object.
+ key_value_array               | labels label_array, OUT keys text[], OUT vals text[]     | record           | key_value_array converts a labels array to two arrays: one for keys and another for values.
+ label_array                   | js jsonb                                                 | label_array      | label_array converts a jsonb to a label array.
+ label_array                   | metric_name text, label_keys text[], label_values text[] | label_array      | label_array converts a metric name, array of keys, and array of values to a label array.
+ matcher                       | labels jsonb                                             | matcher_positive | matcher returns a matcher for the JSONB, __name__ is ignored. The matcher can be used to match against a label array using @> or ? operators.
+ reset_metric_chunk_interval   | metric_name text                                         | boolean          | reset_metric_chunk_interval resets the chunk interval for a specific metric to using the default.
+ reset_metric_retention_period | metric_name text                                         | boolean          | reset_metric_retention_period resets the retention period for a specific metric to using the default.
+ series_id                     | label jsonb                                              | bigint           | series_id returns the series id that exactly matches a JSONB of labels.
+ set_default_chunk_interval    | chunk_interval interval                                  | boolean          | set_default_chunk_interval set the chunk interval for any metrics (existing and new) without an explicit override.
+ set_default_retention_period  | retention_period interval                                | boolean          | set_default_retention_period set the retention period for any metrics (existing and new) without an explicit override.
+ set_metric_chunk_interval     | metric_name text, chunk_interval interval                | boolean          | set_metric_chunk_interval set a chunk interval for a specific metric (this overrides the default).
+ set_metric_retention_period   | metric_name text, new_retention_period interval          | boolean          | set_metric_retention_period set a retention period for a specific metric (this overrides the default).
+ val                           | label_id integer                                         | text             | val returns the label value from a label id.