diff --git a/docs/api.process_nl_query_response.rst b/docs/api.add_responses.rst similarity index 88% rename from docs/api.process_nl_query_response.rst rename to docs/api.add_responses.rst index 91cf353a..ae4211ba 100644 --- a/docs/api.process_nl_query_response.rst +++ b/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,7 +63,7 @@ HTTP 200 code response GROUP BY "zip_code" ORDER BY max_rent DESC LIMIT 1;", - "query_id": "64c424fa3f4036441e882352" + "question_id": "64dbd8cf944f867b3c450467" }' **Response example** @@ -70,9 +71,7 @@ HTTP 200 code response .. 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": [ diff --git a/docs/api.create_database_connection.rst b/docs/api.create_database_connection.rst index 5819a549..dec0ebec 100644 --- a/docs/api.create_database_connection.rst +++ b/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 diff --git a/docs/api.get_question.rst b/docs/api.get_question.rst new file mode 100644 index 00000000..8b162da7 --- /dev/null +++ b/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' \ + '/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" + } diff --git a/docs/api.get_response.rst b/docs/api.get_response.rst new file mode 100644 index 00000000..9011e03d --- /dev/null +++ b/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' \ + '/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 + } diff --git a/docs/api.get_table_description.rst b/docs/api.get_table_description.rst new file mode 100644 index 00000000..c60eaf87 --- /dev/null +++ b/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/ + + +**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' \ + '/api/v1/table-descriptions/64fa09446cec0b4ff60d3ae3 \ + -H 'accept: application/json' diff --git a/docs/api.golden_record.rst b/docs/api.golden_record.rst index 9a470422..8eab7e2d 100644 --- a/docs/api.golden_record.rst +++ b/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 diff --git a/docs/api.list_questions.rst b/docs/api.list_questions.rst new file mode 100644 index 00000000..2de1cf1a --- /dev/null +++ b/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' \ + '/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" + } + ] diff --git a/docs/api.list_responses.rst b/docs/api.list_responses.rst new file mode 100644 index 00000000..32c5c311 --- /dev/null +++ b/docs/api.list_responses.rst @@ -0,0 +1,98 @@ +List responses +============================= + +Once you made a question or you created a new response you can use this endpoint to list the responses + +Request this ``GET`` endpoint:: + + /api/v1/responses + +**Parameters** + +.. csv-table:: + :header: "Name", "Type", "Description" + :widths: 20, 20, 60 + + "question_id", "string", "Filter by question_id to access the historical data, ``Optional``" + + +**Responses** + +HTTP 200 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' \ + '/api/v1/responses?question_id=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 + } + ] diff --git a/docs/api.list_table_description.rst b/docs/api.list_table_description.rst index cca84a0f..e9854af1 100644 --- a/docs/api.list_table_description.rst +++ b/docs/api.list_table_description.rst @@ -15,7 +15,7 @@ Request this ``GET`` endpoint:: :header: "Name", "Type", "Description" :widths: 20, 20, 60 - "db_connection_id", "string", "Filter by connection id, ``Optional``. By configuring this field, it establishes a connection with the database to fetch table names and subsequently merges this data with the pre-existing rows in our MongoDB." + "db_connection_id", "string", "Filter by connection id, ``Required``. By configuring this field, it establishes a connection with the database to fetch table names and subsequently merges this data with the pre-existing rows in our MongoDB." "table_name", "string", "Filter by table name, ``Optional``" **Responses** diff --git a/docs/api.question.rst b/docs/api.question.rst index dcf251d5..31a2f6bf 100644 --- a/docs/api.question.rst +++ b/docs/api.question.rst @@ -12,13 +12,14 @@ Request this ``POST`` endpoint:: .. code-block:: rst - [ - {"nl_question": "question", "sql": "sql_query", "db_connection_id":"db_connection_id"}, - ] + { + "db_connection_id": "string", + "question": "string" + } **Responses** -HTTP 200 code response +HTTP 201 code response .. code-block:: rst @@ -57,7 +58,7 @@ HTTP 200 code response -H 'Content-Type: application/json' \ -d '{ "question": "What is the median rent price for each property type in Los angeles city?", - "db_connection_id": "db_connection_id" + "db_connection_id": "651f2f542aa862650f3e737e" }' **Response example** @@ -65,9 +66,7 @@ HTTP 200 code response .. code-block:: rst { - "id": { - "$oid": "64dbd8f4944f867b3c450468" - }, + "id": "64dbd8f4944f867b3c450468", "question_id": "64dbd8cf944f867b3c450467", "response": "The median rent price for single homes in Los Angeles city is approximately $2827.65.", "intermediate_steps": [ diff --git a/docs/api.rst b/docs/api.rst index 20ac5249..94ae01e1 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -19,8 +19,9 @@ Related endpoints are: * :doc:`Create database connection ` -- ``POST api/v1/database-connections`` * :doc:`List database connections ` -- ``GET api/v1/database-connections`` -* :doc:`Update a database connection ` -- ``PUT api/v1/database-connections/{alias}`` +* :doc:`Update a database connection ` -- ``PUT api/v1/database-connections/{db_connection_id}`` +**Database connection resource example:** .. code-block:: json @@ -29,6 +30,10 @@ Related endpoints are: "use_ssh": false, "connection_uri": "string", "path_to_credentials_file": "string", + "llm_credentials": { + "organization_id": "string", + "api_key": "string" + }, "ssh_settings": { "db_name": "string", "host": "string", @@ -42,30 +47,16 @@ Related endpoints are: } } - -Query Response +Responses ------------------ -The ``query-response`` object is created from the answering natural language questions from the relational data. +The ``responses`` object is created from the answering natural language questions from the relational data. The related endpoints are: -* :doc:`process_nl_query_response ` -- ``POST api/v1/responses`` - -.. code-block:: json - - { - "confidence_score": "string", - "error_message": "string", - "exec_time": "float", - "intermediate_steps":["string"], - "question_id": "string", - "response": "string", - "sql_generation_status": "string", - "sql_query": "string", - "sql_query_result": {}, - "total_cost": "float", - "total_tokens": "int" - } +* :doc:`add_question ` -- ``POST api/v1/questions`` +* :doc:`add_responses ` -- ``POST api/v1/responses`` +* :doc:`list_responses ` -- ``GET api/v1/responses`` +* :doc:`get_response ` -- ``GET api/v1/responses/{response_id}`` Table Descriptions @@ -76,8 +67,11 @@ These are then used to help the LLM build valid SQL to answer natural language q Related endpoints are: * :doc:`Scan table description ` -- ``POST api/v1/table-descriptions/sync-schemas`` -* :doc:`Add table description ` -- ``PATCH api/v1/table-descriptions/{table_description_id}`` +* :doc:`Update a table description ` -- ``PATCH api/v1/table-descriptions/{table_description_id}`` * :doc:`List table description ` -- ``GET api/v1/table-descriptions`` +* :doc:`Get a description ` -- ``GET api/v1/table-descriptions/{table_description_id}`` + +**Table description resource example:** .. code-block:: json @@ -102,6 +96,8 @@ Related endpoints are: * :doc:`Update database instructions ` -- ``PUT api/v1/{db_connection_id}/instructions/{instruction_id}`` * :doc:`Delete database instructions ` -- ``DELETE api/v1/{db_connection_id}/instructions/{instruction_id}`` +**Instruction resource example:** + .. code-block:: json { @@ -118,8 +114,9 @@ Related endpoints are: api.update_database_connection api.scan_table_description - api.add_descriptions api.list_table_description + api.get_table_description + api.update_table_descriptions api.add_instructions api.list_instructions @@ -129,5 +126,9 @@ Related endpoints are: api.golden_record api.question + api.list_questions + api.get_question - api.process_nl_query_response + api.add_responses + api.list_responses + api.get_response diff --git a/docs/api.scan_table_description.rst b/docs/api.scan_table_description.rst index a7bd16ac..f867be7c 100644 --- a/docs/api.scan_table_description.rst +++ b/docs/api.scan_table_description.rst @@ -25,7 +25,7 @@ Request this ``POST`` endpoint:: **Responses** -HTTP 200 code response +HTTP 201 code response .. code-block:: rst diff --git a/docs/api.update_instructions.rst b/docs/api.update_instructions.rst index 2340adca..5e8f03f8 100644 --- a/docs/api.update_instructions.rst +++ b/docs/api.update_instructions.rst @@ -28,7 +28,7 @@ Request this ``PUT`` endpoint:: **Responses** -HTTP 201 code response +HTTP 200 code response .. code-block:: rst diff --git a/docs/api.add_descriptions.rst b/docs/api.update_table_descriptions.rst similarity index 72% rename from docs/api.add_descriptions.rst rename to docs/api.update_table_descriptions.rst index 5e7eadff..c1169b56 100644 --- a/docs/api.add_descriptions.rst +++ b/docs/api.update_table_descriptions.rst @@ -1,9 +1,9 @@ -.. _api.add_descriptions: +.. _api.update_table_descriptions: -Set descriptions +Update table descriptions ======================= -To return an accurate response set descriptions per table and column. +To return an accurate response set descriptions or update the columns per table and column. All request body fields are optional, and only the fields that are explicitly set will be used to update the resource. Request this ``PATCH`` endpoint:: @@ -22,12 +22,19 @@ Request this ``PATCH`` endpoint:: .. code-block:: rst - { - "description": "string", #optional - "columns": [ #optional + { + "description": "string", # Optional + "columns": [ # Optional { - "name": "string", - "description": "string" + "name": "string", # Optional + "description": "string", # Optional + "is_primary_key": false, # Optional + "data_type": "string", # Optional + "low_cardinality": true, # Optional + "categories": [ # Optional + "string" + ], + "foreign_key": false # Optional } ] } @@ -99,5 +106,3 @@ Only set columns descriptions } ] }' - - diff --git a/docs/contributing.projects.rst b/docs/contributing.projects.rst index 79724f15..6e3376f6 100644 --- a/docs/contributing.projects.rst +++ b/docs/contributing.projects.rst @@ -8,4 +8,4 @@ community projects that are in development, spanning areas such as: * Building integrations with front-end frameworks * Testing and benchmarking new NL-to-SQL approaches proposed in academic literature -The best place to jump in is to hop on the #projects channel on our :ref:`Discord server `_ \ No newline at end of file +The best place to jump in is to hop on the #projects channel on our `Discord server `_ diff --git a/docs/envars.rst b/docs/envars.rst index 78e80012..f15c519f 100644 --- a/docs/envars.rst +++ b/docs/envars.rst @@ -34,7 +34,8 @@ provided in the .env.example file with the default values. S3_AWS_ACCESS_KEY_ID = S3_AWS_SECRET_ACCESS_KEY = - ` + + DH_ENGINE_TIMEOUT = .. csv-table:: @@ -60,4 +61,5 @@ provided in the .env.example file with the default values. "MONGODB_DB_PASSWORD", "The password of the MongoDB database", "``admin``", "Yes" "ENCRYPT_KEY", "The key that will be used to encrypt data at rest before storing", "None", "Yes" "S3_AWS_ACCESS_KEY_ID", "The key used to access credential files if saved to S3", "None", "No" - "S3_AWS_SECRET_ACCESS_KEY", "The key used to access credential files if saved to S3", "None", "No " + "S3_AWS_SECRET_ACCESS_KEY", "The key used to access credential files if saved to S3", "None", "No" + "DH_ENGINE_TIMEOUT", "This is used to set the max seconds the process will wait for the response to be generate. If the specified time limit is exceeded, it will trigger an exception", "None", "No"