Implement a Math Functions Package

.github/workflows/build-config.yml

@@ -0,0 +1,31 @@
+name: Build and test SQRL Functions
+on:
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    env:
+      TZ: 'America/Los_Angeles'
+    steps:
+    - name: Setup Timezone
+      uses: szenius/set-timezone@v1.1
+      with:
+        timezoneLinux: "America/Los_Angeles"
+
+    - name: Checkout code
+      uses: actions/checkout@v3
+
+    - name: Build SQRL Functions
+      run: mvn -T 1 -B -U -e clean verify
+
+    - name: Pull datasqrl/cmd Docker image
+      run: docker pull datasqrl/cmd:latest
+
+    - name: Run SQRL Math Test
+      working-directory: ./sqrl-math
+      run: |
+        docker run -i --rm -v $PWD:/build datasqrl/cmd:latest test math.sqrl --snapshot snapshots-math
+      continue-on-error: false

.gitignore

@@ -22,3 +22,7 @@
 # virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
 hs_err_pid*
 replay_pid*
+
+.idea
+target
+build

pom.xml

@@ -0,0 +1,46 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <groupId>com.datasqrl</groupId>
+  <artifactId>sqrl-functions</artifactId>
+  <version>0.5.0-SNAPSHOT</version>
+
+  <packaging>pom</packaging>
+
+  <name>sqrl-functions</name>
+  <url>http://www.datasqrl.com</url>
+  <modules>
+    <module>sqrl-math</module>
+  </modules>
+
+  <properties>
+    <auto-service.version>1.0.1</auto-service.version>
+    <flink-table-api-java-bridge.version>1.19.0</flink-table-api-java-bridge.version>
+    <commons-math3.version>3.6.1</commons-math3.version>
+  </properties>
+
+  <dependencyManagement>
+    <dependencies>
+      <dependency>
+        <groupId>com.google.auto.service</groupId>
+        <artifactId>auto-service</artifactId>
+        <version>${auto-service.version}</version>
+        <scope>provided</scope>
+      </dependency>
+      <dependency>
+        <groupId>org.apache.flink</groupId>
+        <artifactId>flink-table-api-java-bridge</artifactId>
+        <version>${flink-table-api-java-bridge.version}</version>
+        <scope>provided</scope>
+      </dependency>
+
+      <dependency>
+        <groupId>org.apache.commons</groupId>
+        <artifactId>commons-math3</artifactId>
+        <version>${commons-math3.version}</version>
+      </dependency>
+    </dependencies>
+  </dependencyManagement>
+
+</project>

sqrl-math/README.md

@@ -0,0 +1,59 @@
+# SQRL Mathematical Functions
+
+The `datasqrl.math` package provides a collection of advanced mathematical functions for use within the SQRL framework.
+These functions are powered by the `org.apache.commons:commons-math3` library, ensuring robust and accurate mathematical computations.
+
+## Compile and Test Manually
+
+### Step 1: Build the Project
+Ensure that all dependencies are present by running the following Maven package command:
+```bash
+mvn package
+```
+
+### Step 2: Run Your SQRL Script
+
+After the build is complete, make sure to uncomment any required functions or packages in the `math.sqrl` file.
+Then, run your SQRL script along with the schema using the following Docker command:
+```bash
+docker run -i -p 8888:8888 -p 8081:8081 --rm -v $PWD:/build datasqrl/cmd:v0.5.6 run math.sqrl schema.graphqls
+```
+
+### Step 3: Test via GraphQL
+
+Open http://localhost:8888/graphiql/ in your browser and execute the following mutation to insert data:
+```graphql
+mutation {
+    data(input: {
+        d: 1,
+        b:, 1
+    }) {
+        d
+        b
+    }
+}
+```
+
+### Step 4: Retrieve the Results
+
+To view the results, execute the following query:
+```graphql
+{
+    math_results {
+        d
+        b
+        cbrt
+        copy_sign
+        expm1
+        hypot
+        log1p
+        next_after
+        scalb
+        ulp
+        binomial_distribution
+        exponential_distribution
+        normal_distribution
+        poisson_distribution
+    }
+}
+```

sqrl-math/math.sqrl

@@ -0,0 +1,23 @@
+--Uncomment the following line and comment out `IMPORT mock.data;` when running with graphql api.
+--IMPORT schema.data;
+IMPORT mock.data;
+--Uncomment the following line and comment out `IMPORT target.*;` to use the remote package.
+--IMPORT datasqrl.math.*;
+IMPORT target.*;
+
+--Uncomment the following line when running with graphql api.
+/*+test */
+math_results := SELECT d, b,
+            cbrt(d) AS cbrt,
+            copy_sign(d, d) AS copy_sign,
+            expm1(d) AS expm1,
+            hypot(d, d) AS hypot,
+            log1p(d) AS log1p,
+            next_after(d, d) AS next_after,
+            scalb(d, b) AS scalb,
+            ulp(d) AS ulp,
+            binomial_distribution(b, 1, b) AS binomial_distribution,
+            exponential_distribution(d, d) AS exponential_distribution,
+            normal_distribution(d, d, d) AS normal_distribution,
+            poisson_distribution(d, b) AS poisson_distribution
+           FROM data;

sqrl-math/mock/data.schema.yml

@@ -0,0 +1,17 @@
+---
+name: "data"
+schema_version: "1"
+partial_schema: false
+columns:
+- name: "d"
+  type: "DOUBLE"
+  tests:
+  - "not_null"
+- name: "b"
+  type: "BIGINT"
+  tests:
+  - "not_null"
+- name: "epoch_timestamp"
+  type: "BIGINT"
+  tests:
+  - "not_null"

sqrl-math/mock/data.table.json

@@ -0,0 +1,27 @@
+{
+  "version": 1,
+  "flink" : {
+    "connector" : "datagen",
+    "number-of-rows": "10",
+    "fields.d.kind": "sequence",
+    "fields.d.start": "1",
+    "fields.d.end": "10",
+    "fields.b.kind": "sequence",
+    "fields.b.start": "11",
+    "fields.b.end": "20",
+    "fields.epoch_timestamp.kind": "sequence",
+    "fields.epoch_timestamp.start": "1719318565",
+    "fields.epoch_timestamp.end": "1719319565"
+  },
+  "table" : {
+    "type" : "source",
+    "primary-key" : ["d", "b"],
+    "timestamp" : "timestamp",
+    "watermark-millis" : "1"
+  },
+  "metadata" : {
+    "timestamp" : {
+      "attribute" : "time.epochMilliToTimestamp(epoch_timestamp)"
+    }
+  }
+}

sqrl-math/pom.xml

@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>com.datasqrl</groupId>
+        <artifactId>sqrl-functions</artifactId>
+        <version>0.5.0-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>sqrl-math</artifactId>
+
+    <properties>
+        <maven.compiler.source>11</maven.compiler.source>
+        <maven.compiler.target>11</maven.compiler.target>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>com.google.auto.service</groupId>
+            <artifactId>auto-service</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.flink</groupId>
+            <artifactId>flink-table-api-java-bridge</artifactId>
+            <scope>provided</scope>
+        </dependency>
+
+        <dependency>
+            <groupId>org.apache.commons</groupId>
+            <artifactId>commons-math3</artifactId>
+        </dependency>
+    </dependencies>
+
+</project>

sqrl-math/schema.graphqls

@@ -0,0 +1,37 @@
+"An RFC-3339 compliant DateTime Scalar"
+scalar DateTime
+
+type MathResults {
+  d: Float!
+  b: Float!
+  cbrt: Float
+  copy_sign: Float
+  expm1: Float
+  hypot: Float
+  log1p: Float
+  next_after: Float
+  scalb: Float
+  ulp: Float
+  binomial_distribution: Float
+  exponential_distribution: Float
+  normal_distribution: Float
+  poisson_distribution: Float
+}
+
+type Query {
+  math_results(d: Float, b: Float, limit: Int = 10, offset: Int = 0): [MathResults!]
+}
+
+type Mutation {
+  data(input: Data!): DataResponse!
+}
+
+input Data {
+  d: Int!
+  b: Int!
+}
+
+type DataResponse {
+  d: Int!
+  b: Int!
+}

sqrl-math/snapshots-math/math_results.snapshot

@@ -0,0 +1 @@
+{"data":{"math_results":[{"d":10,"b":20.0,"cbrt":2.15443469,"copy_sign":10,"expm1":22025.46579481,"hypot":14.14213562,"log1p":2.39789527,"next_after":10,"scalb":10485760,"ulp":0,"binomial_distribution":1,"exponential_distribution":0.63212056,"normal_distribution":0.5,"poisson_distribution":0.99841174},{"d":9,"b":19.0,"cbrt":2.08008382,"copy_sign":9,"expm1":8102.08392758,"hypot":12.72792206,"log1p":2.30258509,"next_after":9,"scalb":4718592,"ulp":0,"binomial_distribution":1,"exponential_distribution":0.63212056,"normal_distribution":0.5,"poisson_distribution":0.99894405},{"d":8,"b":18.0,"cbrt":2,"copy_sign":8,"expm1":2979.95798704,"hypot":11.3137085,"log1p":2.19722458,"next_after":8,"scalb":2097152,"ulp":0,"binomial_distribution":1,"exponential_distribution":0.63212056,"normal_distribution":0.5,"poisson_distribution":0.99934963},{"d":7,"b":17.0,"cbrt":1.91293118,"copy_sign":7,"expm1":1095.63315843,"hypot":9.89949494,"log1p":2.07944154,"next_after":7,"scalb":917504,"ulp":0,"binomial_distribution":1,"exponential_distribution":0.63212056,"normal_distribution":0.5,"poisson_distribution":0.99963822},{"d":6,"b":16.0,"cbrt":1.81712059,"copy_sign":6,"expm1":402.42879349,"hypot":8.48528137,"log1p":1.94591015,"next_after":6,"scalb":393216,"ulp":0,"binomial_distribution":1,"exponential_distribution":0.63212056,"normal_distribution":0.5,"poisson_distribution":0.99982512},{"d":5,"b":15.0,"cbrt":1.70997595,"copy_sign":5,"expm1":147.4131591,"hypot":7.07106781,"log1p":1.79175947,"next_after":5,"scalb":163840,"ulp":0,"binomial_distribution":1,"exponential_distribution":0.63212056,"normal_distribution":0.5,"poisson_distribution":0.99993099},{"d":4,"b":14.0,"cbrt":1.58740105,"copy_sign":4,"expm1":53.59815003,"hypot":5.65685425,"log1p":1.60943791,"next_after":4,"scalb":65536,"ulp":0,"binomial_distribution":1,"exponential_distribution":0.63212056,"normal_distribution":0.5,"poisson_distribution":0.99998007},{"d":3,"b":13.0,"cbrt":1.44224957,"copy_sign":3,"expm1":19.08553692,"hypot":4.24264069,"log1p":1.38629436,"next_after":3,"scalb":24576,"ulp":0,"binomial_distribution":1,"exponential_distribution":0.63212056,"normal_distribution":0.5,"poisson_distribution":0.9999966},{"d":2,"b":12.0,"cbrt":1.25992105,"copy_sign":2,"expm1":6.3890561,"hypot":2.82842712,"log1p":1.09861229,"next_after":2,"scalb":8192,"ulp":0,"binomial_distribution":1,"exponential_distribution":0.63212056,"normal_distribution":0.5,"poisson_distribution":0.99999979},{"d":1,"b":11.0,"cbrt":1,"copy_sign":1,"expm1":1.71828183,"hypot":1.41421356,"log1p":0.69314718,"next_after":1,"scalb":2048,"ulp":0,"binomial_distribution":1,"exponential_distribution":0.63212056,"normal_distribution":0.5,"poisson_distribution":1}]}}

sqrl-math/sqrl-package/README.md

@@ -0,0 +1,45 @@
+# SQRL Mathematical Functions
+
+The `datasqrl.math` package provides a collection of advanced mathematical functions for use within the SQRL framework.
+
+## Functions Overview
+
+You can use these UDFs in your SQRL scripts to perform advanced mathematical and statistical computations.
+
+| **Function Name**                   | **Description**                                                                                                                                                         |
+|-------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **cbrt(double)**                    | Calculates the cube root of a number. For example, `cbrt(27.0)` returns `3.0`, which is the cube root of 27.0.                                                          |
+| **copy_sign(double, double)**       | Returns the first argument with the sign of the second argument. For example, `copy_sign(2.0, -3.0)` returns `-2.0`.                                                    |
+| **expm1(double)**                   | Calculates e^x - 1 with better precision for small values. For example, `expm1(0.0)` returns `0.0`, as `e^0 - 1 = 0`.                                                   |
+| **hypot(double, double)**           | Computes sqrt(x² + y²) without intermediate overflow or underflow. For example, `hypot(3.0, 4.0)` returns `5.0`, which is the hypotenuse of a 3-4-5 triangle.            |
+| **log1p(double)**                   | Computes the natural logarithm of 1 + x (log(1 + x)) accurately for small x. For example, `log1p(0.0)` returns `0.0` as `log(1 + 0) = 0`.                              |
+| **next_after(double, double)**      | Returns the next floating-point number towards the direction of the second argument. For example, `next_after(1.0, 2.0)` returns the next representable number after 1.0. |
+| **scalb(double, bigint)**           | Multiplies a floating-point number by 2 raised to the power of an integer. For example, `scalb(1.0, 3)` returns `8.0` as `1.0 * 2^3 = 8.0`.                             |
+| **ulp(double)**                     | Returns the size of the unit in the last place (ULP) of the argument. For example, `ulp(1.0)` returns the ULP of 1.0.                                                   |
+| **binomial_distribution(bigint, double, bigint)** | Calculates the probability of obtaining a number of successes in a fixed number of trials for a binomial distribution. For example, `binomial_distribution(10, 0.5, 5)` returns the probability of 5 successes out of 10 trials with a 50% success rate. |
+| **exponential_distribution(double, double)** | Evaluates the probability density or cumulative distribution of an exponential distribution. For example, `exponential_distribution(1.0, 2.0)` returns the exponential distribution's probability for a given rate and time. |
+| **normal_distribution(double, double, double)** | Evaluates the cumulative distribution function for a normal (Gaussian) distribution. For example, `normal_distribution(0.0, 1.0, 1.0)` returns the probability for a standard normal distribution with mean 0 and standard deviation 1. |
+| **poisson_distribution(double, bigint)** | Evaluates the probability mass function of a Poisson-distributed random variable. For example, `poisson_distribution(1.0, 5)` returns the probability of observing 5 events when the average event rate is 1.0. |
+
+## Usage
+
+The `cbrt` function computes the cube root of a given number. It can be useful in mathematical and scientific calculations where you need to find the value that, when cubed, results in the original number.
+
+For example, `cbrt(27)` will return `3`, as \(3^3 = 27\).
+
+### SQRL Example
+
+```sql
+IMPORT schema.entry;
+IMPORT datasqrl.math.*;
+
+-- This query calculates the cube root for a set of values from the entry table
+result_table := 
+    SELECT 
+        cbrt(d) AS cube_root 
+    FROM 
+        entry;
+
+-- Displaying the result
+SELECT * FROM result_table;
+```

sqrl-math/sqrl-package/binomial_distribution.function.json

@@ -0,0 +1 @@
+{"language":"java","functionClass":"com.datasqrl.math.distribution.binomial_distribution","jarPath":"datasqrl/functions/math/sqrl-math-0.5.0-SNAPSHOT.jar"}

sqrl-math/sqrl-package/cbrt.function.json

@@ -0,0 +1 @@
+{"language":"java","functionClass":"com.datasqrl.math.util.cbrt","jarPath":"datasqrl/functions/math/sqrl-math-0.5.0-SNAPSHOT.jar"}

sqrl-math/sqrl-package/copy_sign.function.json

@@ -0,0 +1 @@
+{"language":"java","functionClass":"com.datasqrl.math.util.copy_sign","jarPath":"datasqrl/functions/math/sqrl-math-0.5.0-SNAPSHOT.jar"}

sqrl-math/sqrl-package/expm1.function.json

@@ -0,0 +1 @@
+{"language":"java","functionClass":"com.datasqrl.math.util.expm1","jarPath":"datasqrl/functions/math/sqrl-math-0.5.0-SNAPSHOT.jar"}

sqrl-math/sqrl-package/exponential_distribution.function.json

@@ -0,0 +1 @@
+{"language":"java","functionClass":"com.datasqrl.math.distribution.exponential_distribution","jarPath":"datasqrl/functions/math/sqrl-math-0.5.0-SNAPSHOT.jar"}

sqrl-math/sqrl-package/hypot.function.json

@@ -0,0 +1 @@
+{"language":"java","functionClass":"com.datasqrl.math.util.hypot","jarPath":"datasqrl/functions/math/sqrl-math-0.5.0-SNAPSHOT.jar"}

sqrl-math/sqrl-package/log1p.function.json

@@ -0,0 +1 @@
+{"language":"java","functionClass":"com.datasqrl.math.util.log1p","jarPath":"datasqrl/functions/math/sqrl-math-0.5.0-SNAPSHOT.jar"}

sqrl-math/sqrl-package/next_after.function.json

@@ -0,0 +1 @@
+{"language":"java","functionClass":"com.datasqrl.math.util.next_after","jarPath":"datasqrl/functions/math/sqrl-math-0.5.0-SNAPSHOT.jar"}

sqrl-math/sqrl-package/normal_distribution.function.json

@@ -0,0 +1 @@
+{"language":"java","functionClass":"com.datasqrl.math.distribution.normal_distribution","jarPath":"datasqrl/functions/math/sqrl-math-0.5.0-SNAPSHOT.jar"}

sqrl-math/sqrl-package/package.json

@@ -0,0 +1,16 @@
+{
+  "version": "1",
+  "package": {
+    "name": "datasqrl.math",
+    "version": "0.5.0",
+    "variant": "default",
+    "latest": true,
+    "type": "source",
+    "license": "ASFv2",
+    "repository": "https://github.com/DataSQRL/sqrl-functions/blob/main/sqrl-math",
+    "homepage": "https://github.com/DataSQRL/sqrl-functions/blob/main/sqrl-math/sqrl-package/README.md",
+    "description": "The com.datasqrl.math package offers a set of advanced mathematical functions designed for the SQRL framework, enabling efficient computations such as cube roots, arc tangents, and more.",
+    "documentation": "https://github.com/DataSQRL/sqrl-functions/blob/main/sqrl-math/sqrl-package/README.md",
+    "topics": ["datasqrl", "function", "math"]
+  }
+}

sqrl-math/sqrl-package/poisson_distribution.function.json

@@ -0,0 +1 @@
+{"language":"java","functionClass":"com.datasqrl.math.distribution.poisson_distribution","jarPath":"datasqrl/functions/math/sqrl-math-0.5.0-SNAPSHOT.jar"}

sqrl-math/sqrl-package/scalb.function.json

@@ -0,0 +1 @@
+{"language":"java","functionClass":"com.datasqrl.math.util.scalb","jarPath":"datasqrl/functions/math/sqrl-math-0.5.0-SNAPSHOT.jar"}

sqrl-math/sqrl-package/ulp.function.json

@@ -0,0 +1 @@
+{"language":"java","functionClass":"com.datasqrl.math.util.ulp","jarPath":"datasqrl/functions/math/sqrl-math-0.5.0-SNAPSHOT.jar"}