added some prometheus query language example info

Author: atimgraves

IoTDBJDBC/SetupNotes/PromQL.txt

@@ -0,0 +1,79 @@
+Login to the telementry database as a user with query permisions
+To get the exposed packages execute 
+
+desc DBMS_ADB_TELEMETRY_QUERY
+
+Note that all of the following REQUIRE absolute timestamps Unix Epoch offsets to get that look at https://www.epochconverter.com/ (or risk chatGPT)
+
+this should get the most recent value before the provided timestamp (within 5 mins) for the current charge percentage
+Note The OTEL Naming documents say the use of . as a grouping separator is OK (as long as there are not two concurrent dots - so no ..)
+it does however recomend against the use of upper case (it says should, not must though) and recommends the use of snake case - so the
+metric name would be iot.normalized.current_charge_percentage and the code automaticallu converts any names (attribute key, metric 
+name, attribute name, event name) into dot separated snake_case so
+IN theory a promql would be something like this
+select dbms_ADB_telemetry_query.PROMQL_INSTANT('iot.normalized.current_charge_percentage', 1782926574) from dual
+HOWEVER
+currently there seems to be a bug in the promql parsing code that can't handle the simple from using dot 
+separation, so for now we need to do something like
+select  dbms_cloud_telemetry_query.promql_instant('{__name__="iot.normalized.current_charge_percentage"}',1782928327) from dual;
+
+ADDITIONALLY
+is restricting based on tags there is an additional problem (probabaly a bug to be honest) in that the names (key) of the attributes
+have any . in the name replaced with _, so iot.digital_twin.model_name becoms a tag of iot_digital_twin_model_name which rather messes 
+up the naming hierarchy. Engineering are currently looking to see if this is a ingest "undocumented feature" or a deliberate choice, but
+it's clear from the OTLP naming rules ( https://opentelemetry.io/docs/specs/semconv/general/naming/ ) that . is allowed as a namespace separator
+
+Thge PROMSQL procedures and their arguments are below, note that you can name a param using name -> value, or use positional params 
+based on the order below, all CLOB's are JSOB formatted prometheus structures.
+The promql is defined at https://prometheus.io/docs/prometheus/latest/querying/basics/
+
+
+FUNCTION PROMQL_INSTANT RETURNS CLOB
+the last value of the metric BEFORE or at the time stamp (with a max of 300 seconds prior)
+
+  Argument Name             Type                 In/Out Default?
+  ------------------------- -------------------- ------ --------
+  PROMQL_QUERY              VARCHAR2             IN      
+  INSTANT_TIME_EPOCH        NUMBER               IN      
+  FETCH_SQL                 NUMBER               IN     Y
+
+FUNCTION PROMQL_LABEL RETURNS CLOB
+Get the labels (need more info on this)
+
+  Argument Name             Type                 In/Out Default?
+  ------------------------- -------------------- ------ --------
+  PROMQL_QUERY              VARCHAR2             IN      
+  START_TIME_EPOCH          NUMBER               IN      
+  END_TIME_EPOCH            NUMBER               IN      
+  FETCH_SQL                 NUMBER               IN     Y
+
+FUNCTION PROMQL_RANGE RETURNS CLOB
+The values in the given range
+STEP_SIZE_SECONDS sets the size of the step, which returns a value for each step (like 
+the instant) between the start and end time (defaults to 10 seconds). This is basically
+the PROMQL_INSTANT run once for each step.
+
+  Argument Name             Type                 In/Out Default?
+  ------------------------- -------------------- ------ --------
+  PROMQL_QUERY              VARCHAR2             IN      
+  START_TIME_EPOCH          NUMBER               IN      
+  END_TIME_EPOCH            NUMBER               IN      
+  STEP_SIZE_SECONDS         NUMBER               IN      
+  FETCH_SQL                 NUMBER               IN     Y
+
+FUNCTION PROMQL_SERIES RETURNS CLOB
+Get the labels (need more info on this)
+  Argument Name             Type                 In/Out Default?
+  ------------------------- -------------------- ------ --------
+  PROMQL_QUERY              VARCHAR2             IN      
+  START_TIME_EPOCH          NUMBER               IN      
+  END_TIME_EPOCH            NUMBER               IN      
+  FETCH_SQL                 NUMBER               IN     Y
+
+example (using the current limitations on naming)
+select  dbms_cloud_telemetry_query.promql_instant('{__name__="iot.normalized.inverter_power_watts_point_in_time"}',1782928327) from dual;
+
+getting a set of ranges using the default step of 10
+select  dbms_cloud_telemetry_query.promql_range('{__name__="iot.normalized.InverterPowerWattsPointInTime"}',1782925327, 1782928327) from dual;
+
+getting a set of ranged using a step of 100