DH-4813 Enhance the documentation to reflect the changes introduced in the v0.0.4 release

docs/api.process_nl_query_response.rst → docs/api.add_responses.rst

@@ -1,7 +1,8 @@
-Process a NL query response
+Create a new response
 =============================
 
-Once you made a question you can try sending a new sql query to improve the response, this is not stored
+Once you made a question you can try sending a new sql query to improve the response, this creates a new
+`response` resource related to the `question` resource.
 
 Request this ``POST`` endpoint::
 
@@ -12,13 +13,13 @@ Request this ``POST`` endpoint::
 .. code-block:: rst
 
     {
-      "query_id": "string", # required
+      "question_id": "string", # required
       "sql_query": "string" # required
     }
 
 **Responses**
 
-HTTP 200 code response
+HTTP 201 code response
 
 .. code-block:: rst
 
@@ -62,17 +63,15 @@ HTTP 200 code response
         GROUP BY "zip_code"
         ORDER BY max_rent DESC
         LIMIT 1;",
-      "query_id": "64c424fa3f4036441e882352"
+      "question_id": "64dbd8cf944f867b3c450467"
     }'
 
 **Response example**
 
 .. code-block:: rst
 
    {
-      "id": {
-        "$oid": "64c424fa3f4036441e882352"
-      },
+      "id": "64c424fa3f4036441e882352",
       "question_id": "64dbd8cf944f867b3c450467",
       "response": "The most expensive zip to rent in Los Angeles city is 90210",
       "intermediate_steps": [

docs/api.create_database_connection.rst

@@ -60,7 +60,7 @@ You can find additional details on how to connect to each of the supported data
 
 **Responses**
 
-HTTP 200 code response
+HTTP 201 code response
 
 .. code-block:: rst
 

docs/api.get_question.rst

@@ -0,0 +1,40 @@
+Get a question
+=======================
+
+Once you have made a question you can use this endpoint to list these resources.
+
+Request this ``GET`` endpoint::
+
+   /api/v1/questions/{question_id}
+
+
+**Responses**
+
+HTTP 200 code response
+
+.. code-block:: rst
+
+  {
+    "id": "string",
+    "question": "string",
+    "db_connection_id": "string"
+  }
+
+**Request example**
+
+.. code-block:: rst
+
+   curl -X 'GET' \
+  '<host>/api/v1/questions/64dfa0b603f5134086f7090b' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/json'
+
+**Response example**
+
+.. code-block:: rst
+
+  {
+    "id": "64dfa0b603f5134086f7090b",
+    "question": "what was the most expensive zip code to rent in Los Angeles county in May 2022?",
+    "db_connection_id": "64dfa0e103f5134086f7090c"
+  }

docs/api.get_response.rst

@@ -0,0 +1,86 @@
+Get a response
+=============================
+
+Once you made a question or you created a new response you can use this endpoint to retrieve the specific resource
+
+Request this ``GET`` endpoint::
+
+   /api/v1/responses/{response_id}
+
+
+**Responses**
+
+HTTP 201 code response
+
+.. code-block:: rst
+
+    {
+      "id": "string",
+      "question_id": "string",
+      "response": "string",
+      "intermediate_steps": [
+        "string"
+      ],
+      "sql_query": "string",
+      "sql_query_result": {
+        "columns": [
+          "string"
+        ],
+        "rows": [
+          {}
+        ]
+      },
+      "sql_generation_status": "INVALID",
+      "error_message": "string",
+      "exec_time": 0,
+      "total_tokens": 0,
+      "total_cost": 0,
+      "confidence_score": 0,
+      "created_at": "2023-10-12T16:26:40.951158"
+    }
+
+**Request example**
+
+.. code-block:: rst
+
+   curl -X 'GET' \
+  '<localhost>/api/v1/responses/64c424fa3f4036441e882352' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/json'
+
+**Response example**
+
+.. code-block:: rst
+
+   {
+      "id": "64c424fa3f4036441e882352",
+      "question_id": "64dbd8cf944f867b3c450467",
+      "response": "The most expensive zip to rent in Los Angeles city is 90210",
+      "intermediate_steps": [
+        "",
+      ],
+      "sql_query": "SELECT "zip_code", MAX("metric_value") as max_rent
+        FROM db_table
+        WHERE "dh_county_name" = 'Los Angeles' AND "period_start" = '2022-05-01' AND "period_end" = '2022-05-31'
+        GROUP BY "zip_code"
+        ORDER BY max_rent DESC
+        LIMIT 1;",
+      "sql_query_result": {
+        "columns": [
+          "zip_code",
+          "max_rent"
+        ],
+        "rows": [
+          {
+            "zip_code": "90210",
+            "max_rent": 58279.6479072398192
+          }
+        ]
+      },
+      "sql_generation_status": "VALID",
+      "error_message": null,
+      "exec_time": 37.183526277542114,
+      "total_tokens": 17816,
+      "total_cost": 1.1087399999999998
+      "confidence_score": 0.95
+    }

docs/api.get_table_description.rst

@@ -0,0 +1,66 @@
+.. api.scan_database:
+
+Get a table description
+=======================
+
+This endpoint returns a table description
+
+Request this ``GET`` endpoint::
+
+   /api/v1/table-descriptions/<table_description_id>
+
+
+**Responses**
+
+HTTP 200 code response
+
+.. code-block:: rst
+
+  {
+    "id": "string",
+    "db_connection_id": "string",
+    "table_name": "string",
+    "description": "string",
+    "table_schema": "string",
+    "status": "NOT_SYNCHRONIZED | SYNCHRONIZING | DEPRECATED | SYNCHRONIZED | FAILED"
+    "error_message": "string",
+    "columns": [
+      {
+        "name": "string",
+        "is_primary_key": false,
+        "data_type": "str",
+        "description": "string",
+        "low_cardinality": false,
+        "categories": [
+          "string"
+        ],
+        "foreign_key": {
+          "field_name": "string",
+          "reference_table": "string"
+        }
+      }
+    ],
+    "examples": []
+  }
+
+
+.. csv-table::
+   :header: "Name", "Type", "Description"
+   :widths: 20, 20, 60
+
+   "status", "string", "It can be one of the next options:
+    - `NOT_SYNCHRONIZED` if the table has not been scanned
+    - `SYNCHRONIZING` while the sync schema process is running
+    - `DEPRECATED` if there is a row in our `table-descriptions` collection that is no longer in the database, probably because the table/view was deleted or renamed
+    - `SYNCHRONIZED` when we have scanned the table
+    - `FAILED` if anything failed during the sync schema process, and the `error_message` field stores the error."
+   "error_message", "string", "This field is set only if the async schema process fails"
+
+
+**Request example**
+
+.. code-block:: rst
+
+    curl -X 'GET' \
+      '<localhost>/api/v1/table-descriptions/64fa09446cec0b4ff60d3ae3 \
+      -H 'accept: application/json'

docs/api.golden_record.rst

@@ -27,7 +27,7 @@ Request this ``POST`` endpoint::
 
 **Responses**
 
-HTTP 200 code response
+HTTP 201 code response
 
 .. code-block:: rst
 

docs/api.list_questions.rst

@@ -0,0 +1,57 @@
+List questions
+=======================
+
+Once you have made a question you can use this endpoint to list these resources.
+
+Request this ``GET`` endpoint::
+
+   /api/v1/questions
+
+**Parameters**
+
+.. csv-table::
+   :header: "Name", "Type", "Description"
+   :widths: 20, 20, 60
+
+   "db_connection_id", "string", "Database connection we want to get questions, ``Optional``"
+
+
+**Responses**
+
+HTTP 200 code response
+
+.. code-block:: rst
+
+    [
+      {
+        "id": "string",
+        "question": "string",
+        "db_connection_id": "string"
+      }
+    ]
+
+**Request example**
+
+.. code-block:: rst
+
+   curl -X 'GET' \
+  '<host>/api/v1/questions' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/json'
+
+**Response example**
+
+.. code-block:: rst
+
+    [
+      {
+        "id": "64dfa0b603f5134086f7090b",
+        "question": "what was the most expensive zip code to rent in Los Angeles county in May 2022?",
+        "db_connection_id": "64dfa0e103f5134086f7090c"
+      },
+      {
+        "id": "64dfa19603f5134086f7090e",
+        "question": "what was the most expensive zip code to rent in Los Angeles county in May 2022?",
+        "db_connection_id": "64dfa0e103f5134086f7090c"
+      }
+    ]