From 156b4a9a28040306cd12b73a67c91444d3e9ad53 Mon Sep 17 00:00:00 2001 From: Juan Carlos Jose Camacho Date: Wed, 13 Sep 2023 16:53:55 -0600 Subject: [PATCH] Update documentation and readme file --- docs/api.add_descriptions.rst | 34 +++++- ...rst => api.create_database_connection.rst} | 6 +- docs/api.get_scanned_databases.rst | 67 ----------- docs/api.list_database_connections.rst | 55 +++++++++ docs/api.list_table_description.rst | 60 ++++++++++ docs/api.process_nl_query_response.rst | 107 +++++++++++++++++ docs/api.rst | 17 ++- ...ase.rst => api.scan_table_description.rst} | 8 +- docs/api.update_database_connection.rst | 108 ++++++++++++++++++ ...y.rst => api.update_nl_query_response.rst} | 41 +++++-- 10 files changed, 407 insertions(+), 96 deletions(-) rename docs/{api.database.rst => api.create_database_connection.rst} (97%) delete mode 100644 docs/api.get_scanned_databases.rst create mode 100644 docs/api.list_database_connections.rst create mode 100644 docs/api.list_table_description.rst create mode 100644 docs/api.process_nl_query_response.rst rename docs/{api.scan_database.rst => api.scan_table_description.rst} (73%) create mode 100644 docs/api.update_database_connection.rst rename docs/{api.update_query.rst => api.update_nl_query_response.rst} (69%) diff --git a/docs/api.add_descriptions.rst b/docs/api.add_descriptions.rst index 25de2631..5e7eadff 100644 --- a/docs/api.add_descriptions.rst +++ b/docs/api.add_descriptions.rst @@ -7,7 +7,7 @@ To return an accurate response set descriptions per table and column. Request this ``PATCH`` endpoint:: - /api/v1/scanned-db/{db_name}/{table_name} + /api/v1/table-descriptions/{table_description_id} **Parameters** @@ -16,8 +16,7 @@ Request this ``PATCH`` endpoint:: :header: "Name", "Type", "Description" :widths: 20, 20, 60 - "db_name", "String", "Database name, ``Required``" - "table_name", "String", "Table name, ``Required``" + "table_description_id", "String", "Table description id, ``Required``" **Request body** @@ -39,7 +38,30 @@ HTTP 200 code response .. code-block:: rst - true + { + "id": "string", + "db_connection_id": "string", + "table_name": "string", + "description": "string", + "table_schema": "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": [] + } **Example 1** @@ -48,7 +70,7 @@ Only set a table description .. code-block:: rst curl -X 'PATCH' \ - '/api/v1/scanned-db/foo_db/foo_table' \ + '/api/v1/table-descriptions/64fa09446cec0b4ff60d3ae3' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ @@ -62,7 +84,7 @@ Only set columns descriptions .. code-block:: rst curl -X 'PATCH' \ - '/api/v1/scanned-db/foo_db/foo_table' \ + '/api/v1/table-descriptions/64fa09446cec0b4ff60d3ae3' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ diff --git a/docs/api.database.rst b/docs/api.create_database_connection.rst similarity index 97% rename from docs/api.database.rst rename to docs/api.create_database_connection.rst index 0e9ff1d4..ad5c2799 100644 --- a/docs/api.database.rst +++ b/docs/api.create_database_connection.rst @@ -11,7 +11,7 @@ You can find additional details on how to connect to each of the supported data **Request this POST endpoint**:: - /api/v1/database + /api/v1/database-connections **Request body** @@ -69,7 +69,7 @@ Without a SSH connection .. code-block:: rst curl -X 'POST' \ - '/api/v1/database' \ + '/api/v1/database-connections' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ @@ -85,7 +85,7 @@ With a SSH connection .. code-block:: rst curl -X 'POST' \ - 'http://localhost/api/v1/database' \ + '/api/v1/database-connections' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ diff --git a/docs/api.get_scanned_databases.rst b/docs/api.get_scanned_databases.rst deleted file mode 100644 index 14ac5ee1..00000000 --- a/docs/api.get_scanned_databases.rst +++ /dev/null @@ -1,67 +0,0 @@ -Get a scanned database -============================= - -Once a database was scanned you can use this endpoint to retrieve the -tables names and columns - -Request this ``GET`` endpoint:: - - /api/v1/scanned-databases - -**Parameters** - -.. csv-table:: - :header: "Name", "Type", "Description" - :widths: 20, 20, 60 - - "db_connection_id", "string", "DB connection id, ``Required``" - -**Responses** - -HTTP 200 code response - -.. code-block:: rst - - { - "db_connection_id": "string", - "tables": [ - { - "id": "string", - "name": "string", - "columns": [ - "string" - ] - } - ] - } - -**Request example** - -.. code-block:: rst - - curl -X 'GET' \ - '/api/v1/scanned-databases?db_connection_id=64dfa0e103f5134086f7090c' \ - -H 'accept: application/json' - -**Response example** - -.. code-block:: rst - - { - "db_connection_id": "64dfa0e103f5134086f7090c", - "tables": [ - { - "id": "64dfa18c03f5134086f7090d", - "name": "median_rent", - "columns": [ - "period_start", - "period_end", - "period_type", - "geo_type", - "property_type", - "location_name", - "metric_value" - ] - } - ] - } diff --git a/docs/api.list_database_connections.rst b/docs/api.list_database_connections.rst new file mode 100644 index 00000000..a7fde699 --- /dev/null +++ b/docs/api.list_database_connections.rst @@ -0,0 +1,55 @@ +List Database connections +============================= + +This endpoint list all the existing db connections + +**Request this GET endpoint**:: + + /api/v1/database-connections + + +**Responses** + +HTTP 200 code response + +.. code-block:: rst + + [ + { + "id": "64dfa0e103f5134086f7090c", + "alias": "databricks", + "use_ssh": false, + "uri": "foooAABk91Q4wjoR2h07GR7_72BdQnxi8Rm6i_EjyS-mzz_o2c3RAWaEqnlUvkK5eGD5kUfE5xheyivl1Wfbk_EM7CgV4SvdLmOOt7FJV-3kG4zAbar=", + "path_to_credentials_file": null, + "ssh_settings": null + }, + { + "id": "64e52c5f7d6dc4bc510d6d28", + "alias": "postgres", + "use_ssh": true, + "uri": null, + "path_to_credentials_file": null, + "ssh_settings": { + "db_name": "string", + "host": "string", + "username": "string", + "password": "foo-LWx6c1h6V0KkPRm9O148Pm9scvoO-wnasdasd1dQjf0ZQuFYI07uCjPiMcZ6uC19mUkiiYiHcKyok1NaLaGDAabkwg==", + "remote_host": "string", + "remote_db_name": "string", + "remote_db_password": "bar-LWxpBkRDuasdOwU__Sk4bdzruiYYqiyl8gBEEzCyFYCaCOcbQqOa_OwsS-asdasdsad==", + "private_key_path": "string", + "private_key_password": "fooo-LWxPdFcjQw9lU7CeK_2ELR3jGBq0G_uQ7E2rfPLk2RcFR4aDO9e2HmeAQtVpdvtrsQ_0zjsy9q7asdsadXExYJ0g==", + "db_driver": "string" + } + } + ] + +**Example 1** + +.. code-block:: rst + + curl -X 'GET' \ + '/api/v1/database-connections' \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' + ' diff --git a/docs/api.list_table_description.rst b/docs/api.list_table_description.rst new file mode 100644 index 00000000..39551007 --- /dev/null +++ b/docs/api.list_table_description.rst @@ -0,0 +1,60 @@ +.. api.scan_database: + +List table descriptions +======================= + +Once you have scanned a db connection you can list the table descriptions by requesting this endpoint. + +Request this ``GET`` endpoint:: + + /api/v1/table-descriptions + +**Parameters** + +.. csv-table:: + :header: "Name", "Type", "Description" + :widths: 20, 20, 60 + + "db_connection_id", "string", "Filter by connection id, ``Optional``" + "table_name", "string", "Filter by table name, ``Optional``" + +**Responses** + +HTTP 200 code response + +.. code-block:: rst + + [ + { + "id": "string", + "db_connection_id": "string", + "table_name": "string", + "description": "string", + "table_schema": "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": [] + } + ] + +**Request example** + +.. code-block:: rst + + curl -X 'GET' \ + '/api/v1/table-descriptions?db_connection_id=64fa09446cec0b4ff60d3ae3&table_name=foo' \ + -H 'accept: application/json' diff --git a/docs/api.process_nl_query_response.rst b/docs/api.process_nl_query_response.rst new file mode 100644 index 00000000..3b569307 --- /dev/null +++ b/docs/api.process_nl_query_response.rst @@ -0,0 +1,107 @@ +Process a NL query response +======================= + +Once you made a question you can try sending a new sql query to improve the response, this is not stored + +Request this ``POST`` endpoint:: + + /api/v1/nl-query-responses + +**Request body** + +.. code-block:: rst + + { + "query_id": "string", # required + "sql_query": "string" # required + } + +**Responses** + +HTTP 200 code response + +.. code-block:: rst + + { + "id": "string", + "nl_question_id": "string", + "nl_response": "string", + "intermediate_steps": [ + "string" + ], + "sql_query": "string", + "sql_query_result": { + "columns": [ + "string" + ], + "rows": [ + {} + ] + }, + "sql_generation_status": "NONE", + "error_message": "string", + "exec_time": 0, + "total_tokens": 0, + "total_cost": 0, + "confidence_score": 0 + } + +**Request example** + + +.. code-block:: rst + + curl -X 'POST' \ + '/api/v1/nl-query-responses' \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -d '{ + "sql_query": "SELECT "dh_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;", + "query_id": "64c424fa3f4036441e882352" + }' + +**Response example** + +.. code-block:: rst + + { + "id": { + "$oid": "64c424fa3f4036441e882352" + }, + "nl_question_id": { + "$oid": "64dbd8cf944f867b3c450467" + }, + "nl_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.rst b/docs/api.rst index fea954c0..f156e0f7 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -4,10 +4,17 @@ API .. toctree:: :hidden: - api.database - api.scan_database - api.golden_record + api.create_database_connection + api.list_database_connections + api.update_database_connection + + api.scan_table_description api.add_descriptions + api.list_table_description + + api.golden_record + api.question - api.update_query - api.get_scanned_databases + + api.update_nl_query_response.rst + api.process_nl_query_response diff --git a/docs/api.scan_database.rst b/docs/api.scan_table_description.rst similarity index 73% rename from docs/api.scan_database.rst rename to docs/api.scan_table_description.rst index 7d3a1db1..ed7d057e 100644 --- a/docs/api.scan_database.rst +++ b/docs/api.scan_table_description.rst @@ -6,11 +6,11 @@ Scan a Database Once you have set your db credentials request this endpoint to scan your database. It maps all tables and columns so It will help the SQL Agent to generate an accurate answer. -It can scan all db tables or if you specify a `table_name` then It will only scan that table. +It can scan all db tables or if you specify a `table_names` then It will only scan those tables. Request this ``POST`` endpoint:: - /api/v1/scanner + /api/v1/table-descriptions/scan **Request body** @@ -18,7 +18,7 @@ Request this ``POST`` endpoint:: { "db_connection_id": "string", - "table_name": "string" # Optional + "table_names": ["string"] # Optional } **Responses** @@ -31,7 +31,7 @@ HTTP 200 code response **Request example** -To scan all the tables in a db don't specify a `table_name` +To scan all the tables in a db don't specify a `table_names` .. code-block:: rst diff --git a/docs/api.update_database_connection.rst b/docs/api.update_database_connection.rst new file mode 100644 index 00000000..28f25259 --- /dev/null +++ b/docs/api.update_database_connection.rst @@ -0,0 +1,108 @@ +Update a Database connection +============================= + +This endpoint is used to update a Database connection + +**Request this PUT endpoint**:: + + /api/v1/database-connections/{db_connection_id} + +**Parameters** + +.. csv-table:: + :header: "Name", "Type", "Description" + :widths: 20, 20, 60 + + "db_connection_id", "String", "Set the database connection id, ``Required``" + +**Request body** + +.. code-block:: rst + + { + "alias": "string", + "use_ssh": true, + "connection_uri": "string", + "path_to_credentials_file": "string", + "ssh_settings": { + "db_name": "string", + "host": "string", + "username": "string", + "password": "string", + "remote_host": "string", + "remote_db_name": "string", + "remote_db_password": "string", + "private_key_path": "string", + "private_key_password": "string", + "db_driver": "string" + } + } + +**Responses** + +HTTP 200 code response + +.. code-block:: rst + + { + "id": "64f251ce9614e0e94b0520bc", + "alias": "string_999", + "use_ssh": false, + "uri": "gAAAAABk8lHQNAUn5XARb94Q8H1OfHpVzOtzP3b2LCpwxUsNCe7LGkwkN8FX-IF3t65oI5mTzgDMR0BY2lzvx55gO0rxlQxRDA==", + "path_to_credentials_file": "string", + "ssh_settings": { + "db_name": "string", + "host": "string", + "username": "string", + "password": "gAAAAABk8lHQAaaSuoUKxddkMHw7jerwFmUeiE3hL6si06geRt8CV-r43fbckZjI6LbIULWPZ4HlQUF9_YpfaYfM6FarQbhDUQ==", + "remote_host": "string", + "remote_db_name": "string", + "remote_db_password": "gAAAAABk8lHQpZyZ6ow8EuYPWe5haP-roQbBWkZn3trLgdO632IDoKcXAW-8yjzDDQ4uH03iWFzEgJq8HRxkJTC6Ht7Qrlz2PQ==", + "private_key_path": "string", + "private_key_password": "gAAAAABk8lHQWilFpIbCADvunHGYFMqgoPKIml_WRXf5Yuowqng28DVsq6-sChl695y5D_mWrr1I3hcJCZqkmhDqpma6iz3PKA==", + "db_driver": "string" + } + } + +**Example 1** + +Without a SSH connection + +.. code-block:: rst + + curl -X 'PUT' \ + '/api/v1/database-connections/64f251ce9614e0e94b0520bc' \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -d '{ + "alias": "my_db_alias_identifier", + "use_ssh": false, + "connection_uri": "sqlite:///mydb.db" + }' + +**Example 2** + +With a SSH connection + +.. code-block:: rst + + curl -X 'PUT' \ + '/api/v1/database-connections/64f251ce9614e0e94b0520bc' \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -d '{ + "alias": "my_db_alias", + "use_ssh": true, + "ssh_settings": { + "db_name": "db_name", + "host": "string", + "username": "string", + "password": "string", + "remote_host": "string", + "remote_db_name": "string", + "remote_db_password": "string", + "private_key_path": "string", + "private_key_password": "string", + "db_driver": "string" + } + }' diff --git a/docs/api.update_query.rst b/docs/api.update_nl_query_response.rst similarity index 69% rename from docs/api.update_query.rst rename to docs/api.update_nl_query_response.rst index b7188298..11f3c100 100644 --- a/docs/api.update_query.rst +++ b/docs/api.update_nl_query_response.rst @@ -1,11 +1,11 @@ -Update a query +Update a NL query response ======================= -You can give feedback to improve the queries, and set a query response as a golden query +Once you made a question, you can give feedback to improve the queries Request this ``PATCH`` endpoint:: - /api/v1/query/{query_id} + /api/v1/nl-query-responses/{query_id} **Parameters** @@ -20,8 +20,7 @@ Request this ``PATCH`` endpoint:: .. code-block:: rst { - "sql_query": "string", # optional - "golden_record": true # boolean and optional + "sql_query": "string", # required } **Responses** @@ -30,7 +29,29 @@ HTTP 200 code response .. code-block:: rst - true + { + "id": "string", + "nl_question_id": "string", + "nl_response": "string", + "intermediate_steps": [ + "string" + ], + "sql_query": "string", + "sql_query_result": { + "columns": [ + "string" + ], + "rows": [ + {} + ] + }, + "sql_generation_status": "NONE", + "error_message": "string", + "exec_time": 0, + "total_tokens": 0, + "total_cost": 0, + "confidence_score": 0 + } **Request example** @@ -38,7 +59,7 @@ HTTP 200 code response .. code-block:: rst curl -X 'POST' \ - '/api/v1/query/64c424fa3f4036441e882352' \ + '/api/v1/nl-query-responses/64c424fa3f4036441e882352' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ @@ -47,8 +68,7 @@ HTTP 200 code response 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;", - "golden_record": true + LIMIT 1;" }' **Response example** @@ -88,7 +108,6 @@ HTTP 200 code response "error_message": null, "exec_time": 37.183526277542114, "total_tokens": 17816, - "total_cost": 1.1087399999999998, - "golden_record": true, + "total_cost": 1.1087399999999998 "confidence_score": 0.95 }