Update API: show columns and documents (#2044)

### What problem does this PR solve? 1. show column should be in table scope. 2. update documents. 3. add examples ### Type of change - [x] Documentation Update - [x] Refactoring --------- Signed-off-by: Jin Hai <[email protected]>
infiniflow · Oct 15, 2024 · ddce8bf · ddce8bf
1 parent 1e0ac82
commit ddce8bf
Show file tree

Hide file tree

Showing 14 changed files with 209 additions and 174 deletions.
diff --git a/docs/references/http_api_reference.mdx b/docs/references/http_api_reference.mdx
@@ -318,7 +318,8 @@ curl --request POST \
          "fields": [
              {
                   "name": "name",
-                  "type": "varchar"
+                  "type": "varchar",
+                  "comment": "name column"
              },
              {
                   "name": "score",
@@ -464,6 +465,8 @@ curl --request POST \
         - `"bfloat16"`
   - `"default"`: `Any`, *Optional*  
     The default value for unspecified cells in that column.
+  - `"comment"`: `string`, *Optional*
+    User provided text to describe the column.
 
 ### Response
 

diff --git a/docs/references/pysdk_api_reference.md b/docs/references/pysdk_api_reference.md
@@ -1067,6 +1067,31 @@ table_object.drop_index("my_index")
 
 ---
 
+## show_columns
+
+```python
+table_object.show_columns()
+```
+
+Show the column definition of the current table.
+
+### Returns
+
+An `infinity.local_infinity.table.LocalTable` object in embedded mode or an `infinity.remote_thrift.table.RemoteTable` object in client-server mode.
+
+:::tip NOTE
+This method specifies the projection columns for the current table but does not directly produce displayable data. To display the query results, use `output()` in conjunction with methods like `to_result()`, `to_df()`, `to_pl()`, or `to_arrow()` to materialize the data.
+:::
+
+### Examples
+
+```python
+res = table_object.show_columns()
+print(res)
+```
+
+---
+
 ## list_indexes
 
 ```python

diff --git a/example/http/create_list_show_table.sh b/example/http/create_list_show_table.sh
@@ -23,7 +23,8 @@ curl --request POST \
          "fields": [
              {
                   "name": "name",
-                  "type": "varchar"
+                  "type": "varchar",
+                  "comment": "name column"
              },
              {
                   "name": "score",

diff --git a/example/list_db_tables.py b/example/list_db_tables.py
@@ -37,10 +37,10 @@
     # 'default_db' is the default database
     db_instance = infinity_instance.get_database("db1")
 
-    db_instance.create_table("table1", {
-        "num": {"type": "integer", "constraints": ["PRIMARY KEY"]},
-        "body": {"type": "varchar"},
-        "vec": {"type": "vector, 4, float"},
+    table1_object = db_instance.create_table("table1", {
+        "num": {"type": "integer", "constraints": ["PRIMARY KEY"], "comment": "number column"},
+        "body": {"type": "varchar", "comment": "body column"},
+        "vec": {"type": "vector, 4, float", "comment": "vec column"},
     }, infinity.common.ConflictType.Ignore)
 
     db_instance.create_table("table2", {
@@ -57,6 +57,9 @@
 
     res = db_instance.list_tables()
     print(res.table_names)
+
+    res = table1_object.show_columns()
+    print(res)
     # # Insert 3 rows of data into the 'my_table'
     # table_instance.insert(
     #     [

diff --git a/python/infinity_embedded/db.py b/python/infinity_embedded/db.py
@@ -32,10 +32,6 @@ def list_tables(self):
     def show_table(self, table_name):
         pass  # implement describe table logic here
 
-    @abstractmethod
-    def show_columns(self, table_name):
-        pass  # implement describe table logic here
-
     @abstractmethod
     def get_table(self, table_name):
         pass  # implement get table logic here

diff --git a/python/infinity_embedded/local_infinity/db.py b/python/infinity_embedded/local_infinity/db.py
@@ -84,14 +84,6 @@ def show_table(self, table_name):
         else:
             raise InfinityException(res.error_code, res.error_msg)
 
-    @name_validity_check("table_name", "Table")
-    def show_columns(self, table_name):
-        res = self._conn.show_columns(db_name=self._db_name, table_name=table_name)
-        if res.error_code == ErrorCode.OK:
-            return select_res_to_polars(res)
-        else:
-            raise InfinityException(res.error_code, res.error_msg)
-
     @name_validity_check("table_name", "Table")
     def get_table(self, table_name):
         res = self._conn.get_table(db_name=self._db_name, table_name=table_name)

diff --git a/python/infinity_embedded/local_infinity/table.py b/python/infinity_embedded/local_infinity/table.py
@@ -102,6 +102,13 @@ def drop_index(self, index_name: str, conflict_type: ConflictType = ConflictType
         else:
             raise InfinityException(res.error_code, res.error_msg)
 
+    def show_columns(self):
+        res = self._conn.show_columns(db_name=self._db_name, table_name=self._table_name)
+        if res.error_code == ErrorCode.OK:
+            return select_res_to_polars(res)
+        else:
+            raise InfinityException(res.error_code, res.error_msg)
+
     @name_validity_check("index_name", "Index")
     def show_index(self, index_name: str):
         res = self._conn.show_index(db_name=self._db_name, table_name=self._table_name, index_name=index_name)