Merge branch 'develop' of https://github.com/Canner/vulcan-sql into develop

Author: cyyeh

labs/playground1/Makefile

@@ -6,7 +6,7 @@ start: build test-data/moma.db ../../node_modules
 	@vulcan start
 
 # build the required packages
-build: pkg-core pkg-build pkg-serve pkg-catalog-server pkg-cli pkg-extension-driver-duckdb pkg-extension-authenticator-canner pkg-extension-driver-clickhouse
+build: pkg-core pkg-build pkg-serve pkg-catalog-server pkg-cli pkg-extension-driver-duckdb pkg-extension-authenticator-canner pkg-extension-driver-clickhouse pkg-extension-huggingface
 
 
 # build for core pakge
@@ -62,8 +62,15 @@ pkg-extension-driver-clickhouse: ../../node_modules
 	mkdir -p ./labs/playground1/node_modules/@vulcan-sql; \
 	rm -rf ./labs/playground1/node_modules/@vulcan-sql/extension-driver-clickhouse; \
 	cp -R ./dist/packages/extension-driver-clickhouse ./labs/playground1/node_modules/@vulcan-sql; \
-	cp -R ./packages/extension-driver-clickhouse/node_modules/@clickhouse ./labs/playground1/node_modules
+	cp -R ./packages/extension-driver-clickhouse/node_modules ./labs/playground1
 
+pkg-extension-huggingface: ../../node_modules
+	@cd ../..; \
+	yarn nx build extension-huggingface; \
+	mkdir -p ./labs/playground1/node_modules/@vulcan-sql; \
+	rm -rf ./labs/playground1/node_modules/@vulcan-sql/extension-huggingface; \
+	cp -R ./dist/packages/extension-huggingface ./labs/playground1/node_modules/@vulcan-sql; \
+	cp -R ./packages/extension-huggingface/node_modules ./labs/playground1
 
 # build and install for cli pakge
 pkg-cli: ../../node_modules

packages/doc/docs/extensions/huggingface/huggingface-table-question-answering.mdx

@@ -4,7 +4,9 @@ The [Table Question Answering](https://huggingface.co/docs/api-inference/detaile
 
 Using the `huggingface_table_question_answering` filter.
 
-Sample 1:
+The result will be converted to a JSON string from `huggingface_table_question_answering`. You could decompress the JSON string and use the result by itself.
+
+**Sample 1 - send the data from variable by [set tag](https://vulcansql.com/docs/develop/advance#set-variables):**
 
 ```sql
 {% set data = [
@@ -29,14 +31,36 @@ Sample 1:
 SELECT {{ data | huggingface_table_question_answering(query="How many repositories related to data-lake topic?") }}
 ```
 
-Sample 2:
+**Sample 1 - Response:**
+
+```json
+[
+  {
+    "result": "{\"answer\":\"COUNT > vulcan-sql, accio\",\"coordinates\":[[0,0],[1,0]],\"cells\":[\"vulcan-sql\",\"accio\"],\"aggregator\":\"COUNT\"}"
+  }
+]
+```
+
+**Sample 2 - send the data from [req tag](https://vulcansql.com/docs/develop/predefined-queries):**
 
 ```sql
-{% req products %}
-  SELECT * FROM products
+{% req artists %}
+  SELECT * FROM artists
 {% endreq %}
 
-SELECT {{ products.value() | huggingface_table_question_answering(query="How many products related to 3C type?", model="microsoft/tapex-base-finetuned-wtq", wait_for_model=true, use_cache=true) }}
+{% set question = "List display name where gender are female?" %}
+
+SELECT {{ products.value() | huggingface_table_question_answering(query=question, model="microsoft/tapex-base-finetuned-wtq", wait_for_model=true, use_cache=true) }}
+```
+
+**Sample 2 - Response:**
+
+```json
+[
+  {
+    "result": "{\"answer\":\"Irene Aronson, Ruth Asawa, Isidora Aschheim, Geneviève Asse, Dana Atchley, Aino Aalto, Berenice Abbott\",\"coordinates\":[[8,1],[16,1],[17,1],[23,1],[25,1],[29,1],[35,1]],\"cells\":[\"Irene Aronson\",\"Ruth Asawa\",\"Isidora Aschheim\",\"Geneviève Asse\",\"Dana Atchley\",\"Aino Aalto\",\"Berenice Abbott\"],\"aggregator\":\"NONE\"}"
+  }
+]
 ```
 
 ### Arguments

packages/extension-huggingface/README.md

@@ -33,7 +33,9 @@ The [Table Question Answering](https://huggingface.co/docs/api-inference/detaile
 
 Using the `huggingface_table_question_answering` filter.
 
-Sample 1:
+The result will be converted to a JSON string from `huggingface_table_question_answering`. You could decompress the JSON string and use the result by itself.
+
+**Sample 1 - send the data from variable by [set tag](https://vulcansql.com/docs/develop/advance#set-variables):**
 
 ```sql
 {% set data = [
@@ -55,18 +57,40 @@ Sample 1:
 ] %}
 
 -- The source data for "huggingface_table_question_answering" needs to be an array of objects.
-SELECT {{ data | huggingface_table_question_answering(query="How many repositories related to data-lake topic?") }}
+SELECT {{ data | huggingface_table_question_answering(query="How many repositories related to data-lake topic?") }} as result
+```
+
+**Sample 1 - Response:**
+
+```json
+[
+  {
+    "result": "{\"answer\":\"COUNT > vulcan-sql, accio\",\"coordinates\":[[0,0],[1,0]],\"cells\":[\"vulcan-sql\",\"accio\"],\"aggregator\":\"COUNT\"}"
+  }
+]
 ```
 
-Sample 2:
+**Sample 2 - send the data from [req tag](https://vulcansql.com/docs/develop/predefined-queries):**
 
 ```sql
-{% req products %}
-  SELECT * FROM products
+{% req artists %}
+  SELECT * FROM artists
 {% endreq %}
 
+{% set question = "List display name where gender are female?" %}
+
 -- The "model" keyword argument is optional. If not provided, the default value is 'google/tapas-base-finetuned-wtq'.
 -- The "wait_for_model" keyword argument is optional. If not provided, the default value is false.
 -- The "use_cache" keyword argument is optional. If not provided, the default value is true.
-SELECT {{ products.value() | huggingface_table_question_answering(query="How many products related to 3C type?", model="microsoft/tapex-base-finetuned-wtq", wait_for_model=true, use_cache=true) }}
+SELECT {{ products.value() | huggingface_table_question_answering(query=question, model="microsoft/tapex-base-finetuned-wtq", wait_for_model=true, use_cache=true) }}
+```
+
+**Sample 2 - Response:**
+
+```json
+[
+  {
+    "result": "{\"answer\":\"Irene Aronson, Ruth Asawa, Isidora Aschheim, Geneviève Asse, Dana Atchley, Aino Aalto, Berenice Abbott\",\"coordinates\":[[8,1],[16,1],[17,1],[23,1],[25,1],[29,1],[35,1]],\"cells\":[\"Irene Aronson\",\"Ruth Asawa\",\"Isidora Aschheim\",\"Geneviève Asse\",\"Dana Atchley\",\"Aino Aalto\",\"Berenice Abbott\"],\"aggregator\":\"NONE\"}"
+  }
+]
 ```

packages/extension-huggingface/src/lib/filters/tableQuestionAnswering.ts

@@ -79,11 +79,8 @@ export const TableQuestionAnsweringFilter: FunctionalFilter = async ({
 
   try {
     const results = await request(url, context, token);
-    // result format, convert to suitable FunctionalFilter response => https://huggingface.co/docs/api-inference/detailed_parameters#question-answering-task
-    if (!results.aggregator || results.aggregator === 'NONE')
-      // trim the beginning & ending space if model returned answer exist the space, e.g: ' hello world'
-      return (results.answer as string).trim();
-    return results.cells.join(', ');
+    // convert to JSON string to make user get the whole result after parsing it in SQL
+    return JSON.stringify(results);
   } catch (error) {
     throw new InternalError(
       `Error when sending data to Hugging Face for executing TableQuestionAnswering tasks, details: ${

packages/extension-huggingface/test/tableQuestionAnswering.spec.ts

@@ -26,7 +26,7 @@ const data = [
     description: 'Query Your Data Warehouse Like Exploring One Big View.',
   },
   {
-    repository: 'hell-word',
+    repository: 'hello-world',
     stars: 0,
     topic: [],
     description: 'Sample repository for testing',
@@ -151,6 +151,10 @@ it(
 it(
   'Should get correct expected value when provided "neulab/omnitab-large-1024shot-finetuned-wtq-1024shot" model and wait it for model',
   async () => {
+    const expected = JSON.stringify({
+      // neulab/omnitab-large-1024shot-finetuned-wtq-1024shot will return the result including space in the beginning of the vulcan-sql -> ' vulcan-sql'
+      answer: ' vulcan-sql',
+    });
     const token = process.env['HF_ACCESS_TOKEN'];
     const { compileAndLoad, execute, getExecutedQueries, getCreatedBinding } =
       await getTestCompiler({
@@ -173,28 +177,62 @@ it(
     const bindings = await getCreatedBinding();
 
     expect(queries[0]).toBe('SELECT $1');
-    expect(bindings[0].get('$1')).toEqual('vulcan-sql');
+    expect(bindings[0].get('$1')).toEqual(expected);
   },
   50 * 1000
 );
 
 it.each([
-  { question: 'what repository has most stars?', expected: 'vulcan-sql' },
-  { question: 'what repository has lowest stars?', expected: 'hell-word' },
+  {
+    question: 'what repository has most stars?',
+    expected: {
+      answer: 'vulcan-sql',
+      coordinates: [[0, 0]],
+      cells: ['vulcan-sql'],
+      aggregator: 'NONE',
+    },
+  },
+  {
+    question: 'what repository has lowest stars?',
+    expected: {
+      answer: 'hello-world',
+      coordinates: [[2, 0]],
+      cells: ['hello-world'],
+      aggregator: 'NONE',
+    },
+  },
   {
     question: 'How many stars does the vulcan-sql repository have?',
-    expected: '1000',
+    expected: {
+      answer: 'SUM > 1000',
+      coordinates: [[0, 1]],
+      cells: ['1000'],
+      aggregator: 'SUM',
+    },
   },
   {
     question: 'How many stars does the accio repository have?',
-    expected: '500',
+    expected: {
+      answer: 'AVERAGE > 500',
+      coordinates: [[1, 1]],
+      cells: ['500'],
+      aggregator: 'AVERAGE',
+    },
   },
   {
     question: 'How many repositories related to data-lake topic?',
-    expected: 'vulcan-sql, accio',
+    expected: {
+      answer: 'COUNT > vulcan-sql, accio',
+      coordinates: [
+        [0, 0],
+        [1, 0],
+      ],
+      cells: ['vulcan-sql', 'accio'],
+      aggregator: 'COUNT',
+    },
   },
 ])(
-  'Should get correct expected $answer when asking $question',
+  'Should get correct expected answer when asking question',
   async ({ question, expected }) => {
     // Arrange
 
@@ -220,7 +258,9 @@ it.each([
     const bindings = await getCreatedBinding();
 
     expect(queries[0]).toBe('SELECT $1');
-    expect(bindings[0].get('$1')).toEqual(expected);
+    // parse the result to object and match the expected value
+    const result = JSON.parse(bindings[0].get('$1'));
+    expect(result).toEqual(expected);
   },
   50 * 1000
 );