Ringkasan set konteks

Set data konteks adalah kumpulan informasi khusus database yang memungkinkan alat seperti QueryData membuat kueri dengan akurasi tinggi. Set data konteks mencakup template, facet, dan penelusuran nilai yang membantu QueryData memahami skema database Anda dan logika bisnis aplikasi Anda.

Database berikut didukung:

AlloyDB untuk PostgreSQL
Cloud SQL untuk MySQL
Cloud SQL untuk PostgreSQL
Spanner

Apa yang dimaksud dengan set data konteks

Untuk membuat aplikasi agen yang efektif, alat seperti QueryData harus memahami organisasi data dan logika bisnis Anda. Anda memberikan informasi ini dalam bentuk set data konteks.

Anda menentukan konteks dalam file yang berisi objek JSON untuk setiap jenis konteks. Anda membuat file konteks ini dengan bantuan Gemini CLI. Kemudian, Anda mengupload file konteks ke set data konteks yang Anda buat di Google Cloud konsol. Proses ini memungkinkan alat seperti QueryData mempelajari skema database dan logika bisnis aplikasi tertentu.

File konteks terlihat mirip dengan berikut ini:

{
  "templates": [
    {
      "nl_query": "Count Prague loan accounts",
      "sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" ='Prague'",
      "intent": "How many accounts associated with loans are located in the Prague region?",
      "manifest": "How many accounts associated with loans are located in a given city?",
      "parameterized": {
        "parameterized_intent": "How many accounts associated with loans are located in $1",
        "parameterized_sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = $1"
      }
    }
  ],
  "facets": [
    {
      "sql_snippet": "employee.\"A11\" BETWEEN 6000 AND 10000",
      "intent": "Average salary between 6000 and 10000",
      "manifest": "Average salary between a given number and a given number",
      "parameterized": {
         "parameterized_intent": "Average salary between $1 and $2",
         "parameterized_sql_snippet": "employee.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ],
  "value_searches": [
    {
      "query": "SELECT $value as value, 'accounts.account_type' as columns, 'Account Type' as concept_type, 0 as distance, '{}'::text as context FROM \"accounts\" T WHERE T.\"account_type\" = $value",
      "concept_type": "Account Type",
      "description": "Exact match for account types"
    }
   ]
}

Format file set data konteks

File set data konteks terdiri dari kumpulan template dan facet yang dikurasi dalam format JSON yang memandu alat seperti QueryData dalam menerjemahkan pertanyaan bahasa alami menjadi kueri untuk database tertentu. Menentukan konteks memastikan pembuatan SQL dengan akurasi tinggi untuk pola kueri umum.

Pastikan set data konteks akurat dan komprehensif dalam cakupan kueri aplikasi yang diharapkan untuk memaksimalkan akurasi.

Set data konteks dapat dibuat di region us-central1, us-east1, europe-west4, dan asia-southeast1.

Template kueri

Template kueri adalah kumpulan pertanyaan bahasa alami representatif yang dikurasi dengan kueri SQL yang sesuai. Template kueri juga menyertakan penjelasan untuk memberikan alasan deklaratif untuk pembuatan bahasa alami ke SQL.

Objek template kueri terlihat mirip dengan berikut ini:

{
  "templates": [
    {
      "nl_query": "Count prague loan accounts",
      "sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = 'Prague'",
      "intent": "How many accounts associated with loans are located in the Prague region?",
      "manifest": "How many accounts associated with loans are located in a given city?",
      "parameterized": {
        "parameterized_intent": "How many accounts associated with loans are located in $1",
        "parameterized_sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = $1"
      }
    }
  ]
},
...

Komponen utama objek JSON template kueri adalah sebagai berikut:

nl_query: Contoh kueri bahasa alami yang ditangani oleh alat seperti QueryData.
sql: Kueri SQL untuk kueri bahasa alami.
intent: Sasaran atau tujuan kueri bahasa alami. Jika tidak ditetapkan, nilai ini akan ditetapkan secara default ke kueri bahasa alami.
manifest: Bentuk tujuan yang digeneralisasi dan dibuat secara otomatis.
parameterized_intent: Bentuk tujuan yang dibuat secara otomatis dan menggunakan template, dengan nilai entity diganti dengan parameter.
parameterized_sql: Bentuk kueri SQL yang dibuat secara otomatis dan menggunakan template yang sesuai dengan tujuan yang diparameterkan.

Facet kueri adalah kumpulan kondisi bahasa alami representatif yang dikurasi dengan predikat SQL yang sesuai. Facet mengelola pemfilteran dan kondisi, yang memungkinkan template kueri melakukan penelusuran berfacet.

Objek facet kueri terlihat mirip dengan berikut ini:

{
...
"facets": [
    {
      "sql_snippet": "employee.\"A11\" BETWEEN 6000 AND 10000",
      "intent": "Average salary between 6000 and 10000",
      "manifest": "Average salary between a given number and a given number",
      "parameterized": {
         "parameterized_intent": "Average salary between $1 and $2",
         "parameterized_sql_snippet": "employee.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ]
}

Komponen utama objek JSON facet adalah sebagai berikut:

sql_snippet: Snippet SQL. Untuk menghindari ambiguitas, tentukan nama kolom dengan nama tabel (misalnya, table_name.column_name).
intent: Penjelasan tentang predikat SQL.
manifest: Bentuk tujuan yang digeneralisasi dan dibuat secara otomatis.
parameterized_intent: Bentuk tujuan yang dibuat secara otomatis dan menggunakan template, dengan nilai entity diganti dengan parameter.
parameterized_sql_snippet: Bentuk sql_snippet yang dibuat secara otomatis dan menggunakan template yang sesuai dengan tujuan yang diparameterkan.

Kueri penelusuran nilai

Kueri penelusuran nilai adalah kueri yang ditentukan developer yang menggunakan fungsi pencocokan untuk menemukan nilai dan konteksnya dalam database. Penautan nilai menggunakan hasil kueri ini untuk mengidentifikasi tabel dan kolom mana yang berisi nilai yang cocok, memahami jenis konsep nilai, dan mengoreksi salah eja.

QueryData API menggunakan penautan nilai untuk mengonversi bahasa alami menjadi SQL dengan lebih akurat. Dengan menggunakan kueri penelusuran nilai, API dapat mengoreksi salah eja dan menyelesaikan jenis nilai berdasarkan nilai database, sehingga meningkatkan akurasi konversi.

Penautan nilai meningkatkan akurasi konversi bahasa alami ke SQL. Misalnya, jika pengguna bertanya, "Apakah ada penerbangan dari Heathrow?", database mungkin menyimpan nama bandara sebagai "London Heathrow". Tanpa penautan nilai, SQL yang dibuat mungkin memfilter berdasarkan WHERE name = 'Heathrow' dan tidak menampilkan hasil. Kueri penelusuran nilai memandu agen untuk memetakan "Heathrow" ke nilai database yang benar "London Heathrow" dan lokasi skemanya (airports.name), sehingga memastikan SQL yang dibuat akurat.

Contoh kueri penelusuran nilai adalah:

{
  ...
  "value_searches": [
    {
      "query": "SELECT $value as value, 'airports.iata' as columns, 'Airport IATA Code' as concept_type, 0 as distance, '{}'::text as context FROM \"airports\" T WHERE T.\"iata\" = $value",
      "concept_type": "Airport IATA Code",
      "description": "Exact match (Standard SQL) for 3-letter airport codes"
    },
    {
      "query": "WITH TrigramMetrics AS ( SELECT T.\"name\" AS original_value, (T.\"name\" <-> $value::text) AS normalized_dist FROM \"airports\" T WHERE T.\"name\" % $value::text ) SELECT original_value AS value, 'airports.name' AS columns, 'Airport Name' AS concept_type, normalized_dist AS distance, '{}'::text AS context FROM TrigramMetrics",
      "concept_type": "Airport Name",
      "description": "Fuzzy match using standard trigram for partial airport names"
    }
  ]
}

Komponen utama objek JSON penelusuran nilai adalah sebagai berikut:

query: Pernyataan SQL yang diparameterkan yang menentukan logika untuk mencocokkan frasa nilai dengan nilai yang disimpan dalam kolom tabel di database. Kumpulan hasil biasanya memproyeksikan nilai yang cocok, lokasi skema, jenis konsep, dan metrik jarak yang dinormalisasi (antara 0 dan 1).
concept_type: Label semantik yang ditetapkan ke nilai—misalnya, district atau loan_status. Label ini membantu penautan nilai dan akhirnya alat seperti QueryData API untuk memahami peran frasa nilai dalam skema. Label ini juga membantu menghasilkan pernyataan SQL yang menargetkan konsep untuk nilai, serta tabel dan kolom tempat frasa nilai muncul.
description: Deskripsi logika penelusuran.

Batasan

Set data konteks memiliki batasan berikut:

Set data konteks untuk database hanya mendukung template, facet, dan penelusuran nilai.
Set data konteks untuk database hanya digunakan oleh endpoint QueryData di Conversational Analytics API.

Langkah berikutnya

Pelajari cara membuat atau menghapus set data konteks di Spanner Studio.