Sintaksis penelusuran untuk Knowledge Catalog

Kueri penelusuran di Knowledge Catalog memungkinkan Anda menemukan aset data tertentu di seluruh katalog menggunakan pencocokan semantik dan kata kunci. Dengan menggabungkan bahasa alami, filter metadata, dan operator logis, Anda dapat menemukan entri yang relevan untuk menemukan, mengelola, dan memahami data organisasi Anda.

Knowledge Catalog juga mendukung mode penelusuran khusus kata kunci untuk kompatibilitas mundur. Untuk mengetahui informasi selengkapnya tentang mode ini, filternya, dan cara menggunakannya, lihat Penelusuran khusus kata kunci.

Ringkasan sintaksis kueri

Anda dapat membuat kueri penelusuran Knowledge Catalog menggunakan komponen berikut:

  • Penelusuran sederhana: Temukan aset data menggunakan satu istilah penelusuran.
  • Penelusuran teks bebas: Temukan aset data menggunakan frasa atau kata kunci bahasa alami.
  • Predikat terpilih: Saring penelusuran Anda menggunakan kolom metadata tertentu, seperti nama, lokasi, sistem, atau jenis.
  • Penelusuran aspek: Menelusuri entri berdasarkan metadata bisnis dan teknis yang dilampirkan.
  • Operator logika: Gabungkan beberapa kriteria penelusuran menggunakan operator AND, OR, atau NOT untuk membuat kueri yang kompleks.

Predikat terpilih

Gunakan predikat terpilih untuk mempersempit hasil penelusuran dengan secara eksplisit menginstruksikan penelusuran untuk mengevaluasi kolom metadata tertentu, seperti nama, jenis, atau sistem aset.

Anda dapat mengualifikasi predikat dengan mengawalinya dengan kunci yang membatasi pencocokan ke bagian metadata tertentu:

  • Tanda sama dengan (=) untuk membatasi penelusuran pada pencocokan persis.
  • Titik dua (:) setelah kunci untuk mencocokkan predikat dengan substring atau token dalam nilai di hasil penelusuran.

Tokenisasi membagi aliran teks menjadi serangkaian token, dengan setiap token biasanya sesuai dengan satu kata.

Contoh:

  • name:foo memilih resource dengan nama yang berisi substring foo, seperti foo1 dan barfoo.
  • description:foo memilih resource dengan token foo dalam deskripsi, seperti bar dan foo.
  • location=foo mencocokkan resource di lokasi yang ditentukan dengan foo sebagai nama lokasi.

Penentu yang didukung

Penelusuran Knowledge Catalog mendukung penentu berikut:

Penentu Deskripsi
name:x Mencocokkan x sebagai substring ID resource atau nama tampilan resource.
displayname:x Mencocokkan x sebagai substring nama tampilan resource.
column:x Mencocokkan x sebagai substring nama kolom (atau nama kolom bertingkat) dalam skema resource.
description:x Mencocokkan x sebagai token dalam deskripsi resource. Contoh:
  • description:"products" menampilkan semua resource yang memiliki token products dalam deskripsi. Misalnya, "daftar produk dalam inventaris".
  • description:"prod" tidak menampilkan resource yang memiliki token products dalam deskripsi. Namun, penelusuran ini akan menampilkan semua resource yang memiliki token prod dalam deskripsi. Misalnya, "lingkungan produksi".
labels:bar Mencocokkan resource yang memiliki label (dengan beberapa nilai) dan kunci label memiliki bar sebagai substring.
labels=bar Mencocokkan resource yang memiliki label (dengan beberapa nilai) dan kunci label sama dengan bar sebagai string.
labels.bar:x Mencocokkan x sebagai substring dalam nilai label dengan kunci bar yang dilampirkan ke resource.
labels.foo=bar Mencocokkan resource yang kuncinya sama dengan foo dan nilai kuncinya sama dengan bar.
type=TYPE Mencocokkan resource dari jenis entri tertentu atau alias jenisnya. Memerlukan penentu =.
projectid:bar Mencocokkan resource dalam project Google Cloud yang cocok dengan bar sebagai substring dalam ID.
parent:x Cocok dengan x sebagai substring jalur hierarkis resource.
system=SYSTEM Mencocokkan resource dari sistem yang ditentukan. Memerlukan penentu =.
location=LOCATION

Mencocokkan resource di lokasi yang ditentukan dengan nama yang sama persis. Memerlukan penentu =. Misalnya, location=us-central1 cocok dengan aset yang dihosting di Iowa.

Aset BigQuery Omni mendukung penentu ini menggunakan nama lokasi BigQuery Omni. Misalnya, location=aws-us-east-1 cocok dengan aset BigQuery Omni di Northern Virginia.

createtime

Menemukan resource yang dibuat dalam, sebelum, atau setelah tanggal, stempel waktu, atau waktu relatif tertentu dalam hari. Untuk mengetahui format dan operator yang didukung, lihat Filter waktu.
updatetime

Menemukan resource yang diperbarui dalam, sebelum, atau setelah tanggal, stempel waktu, atau waktu relatif tertentu dalam hari. Untuk mengetahui format dan operator yang didukung, lihat Filter waktu.

Penentu pencocokan persis

Kunci predikat type, system, location, dan penelusuran aspek (tidak termasuk has) hanya mendukung penentu pencocokan persis (=), bukan penentu substring (:).

Gunakan sintaksis pencocokan persis berikut untuk predikat ini:

Kunci predikat Sintaksis benar Sintaksis salah
type type=table (atau type=view, type=dataset) type:table atau type:tab
system system=bigquery (atau system=spanner) system:bigquery atau system:big
location location=us-central1 (atau location=europe-west1) location:us-central1 atau location:us

Penentu substring

Predikat seperti name, displayname, column, projectid, dan parent, mendukung pencocokan substring dengan penentu titik dua (:):

  • name:transactions cocok dengan resource yang ID atau nama tampilannya berisi transactions. Misalnya, daily_transactions_raw dan transactions_v2.
  • column:customer_id mencocokkan resource dengan nama kolom yang berisi customer_id.
  • projectid:prod mencocokkan resource dalam project yang ID-nya berisi prod. Misalnya, finance-prod-2026.

Filter waktu

Anda dapat memfilter resource berdasarkan waktu pembuatan (createtime) atau waktu update terakhir (updatetime).

Operator dan format yang didukung

  • Operator yang didukung: :, =, <, >, <=, >=, =>, =<
  • Hari relatif (-Nd): Filter menurut jumlah hari relatif di masa lalu (misalnya, -30d, -7d, -1d).
  • Tanggal kalender (YYYY-MM-DD atau YYYY/MM/DD): Memfilter menurut tanggal tertentu dalam GMT/UTC.
  • Stempel waktu lengkap (YYYY-MM-DDTHH:MM:SS atau YYYY-MM-DDTHH:MM:SSZ): Filter menurut stempel waktu yang tepat dalam GMT/UTC. Stempel waktu parsial, seperti YYYY-MM-DDTHH:MM atau YYYY-MM-DDTHH, juga didukung.

Sintaksis filter waktu

Tabel berikut menjelaskan sintaksis filter waktu:

Kategori format Sintaksis valid Sintaksis tidak valid Deskripsi
Unit waktu relatif
  • createtime>-30d (30 hari terakhir)
  • createtime<=-7d (7 hari lalu atau lebih awal)
  • updatetime=-1d (hari sebelumnya)
  • updatetime>=-90d
  • createtime>-24h
  • createtime>-60m
  • createtime>-2w
  • createtime>30d
  • Hanya unit hari negatif (-Nd) yang didukung untuk waktu relatif.
  • Unit yang lebih pendek (jam h, menit m) dan unit yang lebih panjang (minggu w, bulan m) tidak didukung.
  • Offset positif tanpa tanda minus di awal (-) tidak valid.
Tanggal kalender
  • createtime:2025-01-15
  • createtime>2025-01-01
  • createtime<=2025-06-30
  • createtime:2025/01/15
  • createtime:2025-01
  • createtime:2025
  • createtime:15-01-2025
  • createtime:Jan-15-2025
  • createtime:01/15/2025
  • Tanggal harus mengikuti format YYYY-MM-DD atau YYYY/MM/DD.
  • Format dengan urutan komponen yang tidak standar (seperti DD-MM-YYYY atau MM/DD/YYYY) atau nama bulan tidak valid.
Stempel waktu dan zona waktu
  • createtime:2025-01-15T05:30:00
  • createtime>2025-01-15T05:30:00Z
  • createtime:2025-01-15T05:30
  • createtime:2025-01-15T05:30:00-08:00
  • createtime:2025-01-15T05:30:00 EST
  • createtime:2025-01-15T05:30:00+05:30
  • Semua stempel waktu dievaluasi dalam GMT/UTC.
  • Offset zona waktu non-GMT (seperti -08:00 atau +05:30) dan singkatan zona waktu (seperti EST atau PST) tidak didukung.
Rentang waktu
  • createtime>=2025-01-15T09:00:00 createtime<=2025-01-15T17:00:00
  • createtime:09:00:00..17:00:00
  • createtime:09:00-17:00
  • Sintaksis rentang waktu tidak didukung.
  • Sebagai gantinya, gunakan perbandingan batas bawah dan atas yang terpisah dengan string tanggal-waktu lengkap.
Tanggal dalam bahasa alami
  • createtime=-1d
  • createtime>-30d
  • createtime:yesterday
  • createtime:"last week"
  • createtime:today
  • Frasa tanggal bahasa alami tidak didukung dalam penentu createtime atau updatetime.
  • Gunakan sintaksis hari relatif (-1d, -7d) atau tanggal eksplisit.

Filter label

Gunakan predikat labels untuk memfilter resource berdasarkan label yang dilampirkan. Anda dapat memfilter berdasarkan kunci label, nilai label, atau keduanya:

Pola kueri Contoh Deskripsi
labels=KEY labels=environment Mencocokkan resource yang memiliki label dengan kunci environment yang sama persis, terlepas dari nilainya.
labels:KEY_SUBSTRING labels:tier Mencocokkan resource dengan kunci label yang berisi tier sebagai substring (seperti service_tier atau storage_tier).
labels.KEY=VALUE labels.env=prod Mencocokkan resource yang kunci labelnya adalah env dan nilainya sama persis dengan prod.
labels.KEY:VALUE_SUBSTRING labels.owner:analytics Mencocokkan resource dengan kunci label owner yang nilainya berisi analytics sebagai substring (seperti analytics-team atau data-analytics).
Beberapa label (AND) labels.env=prod labels.data_tier=tier1 Mencocokkan resource yang memiliki label env=prod dan data_tier=tier1 yang dilampirkan.
Dikombinasikan dengan sistem dan jenis system=bigquery type=table labels.env=prod labels.confidentiality=high Cocok dengan tabel BigQuery yang diberi label env=prod dan confidentiality=high.

Anda dapat menggunakan sintaksis kueri untuk menelusuri entri berdasarkan aspek yang dilampirkan.

Pencocokan substring mencoba mencocokkan dengan sejumlah aspek yang terbatas. Jika Anda tidak dapat menemukan entri menggunakan fragmen jalur, gunakan jalur lengkap untuk mempersempit penelusuran dan meningkatkan perolehan.

Penentu Deskripsi
aspect:x
atau
has:x		 Mencocokkan x sebagai substring dari jalur lengkap ke jenis aspek dari aspek yang dilampirkan ke entri, dalam format projectid.location.ASPECT_TYPE_ID
aspect=x
atau
has=x		 Cocok dengan x sebagai jalur lengkap ke jenis aspek dari aspek yang dilampirkan ke entri, dalam format projectid.location.ASPECT_TYPE_ID
x
OPERATOR
value

Menelusuri nilai kolom aspek. Cocok dengan x sebagai substring jalur lengkap ke jenis aspek dan nama kolom aspek yang dilampirkan ke entri, dalam format berikut:

  • Sintaksis untuk jenis aspek sistem:

    • ASPECT_TYPE_ID.FIELD_NAME
    • dataplex-types.ASPECT_TYPE_ID.FIELD_NAME
    • dataplex-types.LOCATION.ASPECT_TYPE_ID.FIELD_NAME

    Misalnya, kueri berikut cocok dengan entri yang nilai kolom type dalam aspek bigquery-dataset adalah default:

    • bigquery-dataset.type=default
    • dataplex-types.bigquery-dataset.type=default
    • dataplex-types.global.bigquery-dataset.type=default

  • Sintaksis untuk jenis aspek kustom:

    • Jika aspek dibuat di region global: PROJECT_ID.ASPECT_TYPE_ID.FIELD_NAME
    • Jika aspek dibuat di region tertentu: PROJECT_ID.REGION.ASPECT_TYPE_ID.FIELD_NAME

    Misalnya, kueri berikut cocok dengan entri yang nilai kolom is-enrolled dalam aspek employee-info adalah true.

    • example-project.us-central1.employee-info.is-enrolled=true
    • example-project.employee-info.is-enrolled=true

    Daftar operator yang didukung bergantung pada jenis kolom dalam aspek, sebagai berikut:

    • String: = (pencocokan persis)
    • Semua jenis angka: =, :, <, >, <=, >=, =>, =<
    • Enum: =
    • Tanggal dan waktu: sama seperti untuk angka, tetapi nilai yang akan dibandingkan diperlakukan sebagai tanggal dan waktu, bukan angka
    • Boolean: =

Hanya kolom tingkat teratas dari aspek yang dapat ditelusuri.

Operator logika

Kueri dapat menggabungkan beberapa predikat menggunakan operator logika. Catatan: Operator logika AND, OR, dan NOT peka huruf besar/kecil dan harus dalam huruf besar.

Operator AND

Jika Anda memisahkan beberapa istilah penelusuran atau predikat dengan spasi, AND logis akan tersirat, yang berarti Anda tidak perlu menulisnya secara eksplisit.

Contoh berikut menunjukkan cara membuat kueri dengan operator AND.

  • Menelusuri tabel BigQuery

    system=bigquery type=table

  • Telusuri resource dalam project banking-prod dengan kolom bernama customer_id

    projectid:banking-prod column:customer_id

  • Jika diperlukan, Anda dapat menggunakan operator AND eksplisit:

    system=bigquery AND type=table AND location=us-central1

Operator OR

Gunakan operator OR untuk mencocokkan salah satu dari beberapa kondisi. Saat menggabungkan OR dengan kriteria lain, gunakan tanda kurung ( ) untuk mengelompokkan ekspresi dan menentukan prioritas.

Contoh berikut menunjukkan cara membuat kueri dengan operator OR.

  • Menelusuri tabel dan tampilan BigQuery

    system=bigquery (type=table OR type=view)

  • Menelusuri tabel di beberapa sistem

    (system=bigquery OR system=spanner) type=table

  • Menelusuri entri di set data pemasaran atau keuangan

    system=bigquery (parent:marketing_analytics OR parent:finance_analytics)

Operator NOT

Anda dapat meniadakan predikat dengan menambahkan awalan NOT dalam huruf besar atau - (tanda hubung).

Contoh berikut menunjukkan cara membuat kueri dengan operator NOT.

  • Menemukan semua tabel kecuali yang ada di project sandbox

    • Menggunakan operator NOT
    type=table NOT projectid:sandbox-project
    • Gunakan tanda hubung
    type=table -projectid:sandbox-project

  • Menemukan semua resource BigQuery yang tidak berisi test dalam namanya

    system=bigquery -name:test

Sintaksis yang disingkat

Jika Anda ingin menggunakan sintaksis singkat, gunakan | (garis vertikal) untuk operator OR dan , (koma) untuk operator AND dalam tanda kurung. Sintaksis singkat ini berfungsi untuk predikat terpilih.

  • Menelusuri di beberapa project ID

    • Gunakan operator OR:
    projectid:(finance-prod|sales-prod|analytics-prod)
    • Gunakan tanda kurung:
    projectid:finance-prod OR projectid:sales-prod OR projectid:analytics-prod

  • Menelusuri entri yang cocok dengan beberapa nama kolom (AND)

    column:(customer_id,transaction_date,amount)

  • Menelusuri entri yang cocok dengan salah satu dari beberapa nama kolom (OR)

    column:(customer_id|user_id|client_id)

Kebijakan karakter pengganti

Sintaksis penelusuran Knowledge Catalog tidak mendukung karakter pengganti, seperti * atau ?, dalam string kueri atau predikat.

Jika Anda menyertakan tanda bintang (*) atau tanda tanya (?) dalam kueri, tanda tersebut akan diperlakukan sebagai karakter literal, bukan karakter pengganti pencocokan pola.

Misalnya, untuk menelusuri tabel yang namanya diakhiri dengan _masked:

  • Didukung: name:_masked : menggunakan penentu kecocokan substring : untuk menemukan semua resource yang namanya berisi _masked, seperti customer_records_masked atau transactions_masked.
  • Tidak didukung: name:*_masked: * diperlakukan sebagai karakter literal, bukan karakter pengganti pola.

Tanda kurung

Tanda kurung dalam kueri penelusuran memiliki fungsi teknis tertentu. Jika Anda terlalu sering menggunakan tanda kurung atau menerapkannya ke kueri bahasa alami, Anda dapat membingungkan parser penelusuran dan menurunkan kualitas hasil.

Bahasa alami yang sederhana

Saat mengajukan pertanyaan bisnis, teruskan kueri dalam teks biasa. Jangan mengapitnya dalam tanda kurung. Misalnya, tulis:

Find customer orders containing email addresses

Sintaksis predikat yang disingkat

Tanda kurung sangat efektif jika digunakan dengan kunci predikat untuk mencantumkan beberapa kondisi OR dan AND dalam format yang ringkas.

  • Mengelompokkan kunci predikat dengan OR (|)

    • Telusuri entri yang berada di salah satu project yang tercantum menggunakan (|)

      projectid:(finance-prod|finance-test|analytics-raw)

    • Telusuri entri yang berada di salah satu project yang tercantum menggunakan (OR)

    projectid:finance-prod OR projectid:finance-test OR projectid:finance-raw

  • Mengelompokkan kunci predikat dengan AND (,)

    • Telusuri entri yang berisi semua kolom yang ditentukan menggunakan (,)
    column:(customer_id, order_date, total_amount)
    • Telusuri entri yang berisi semua kolom yang ditentukan menggunakan (AND)
    column:customer_id AND column:order_date AND column:total_amount

Anda dapat menggabungkan kueri bahasa alami dengan filter ringkas.

Misalnya, untuk menemukan tabel yang menentukan pengguna aktif bulanan, tetapi membatasi penelusuran ke project yang ditentukan, gunakan kueri berikut:

monthly active users type=table projectid:(data-warehouse|analytical-tier)

Praktik terbaik untuk menggunakan tanda kurung

  • Jangan mengapit seluruh pertanyaan dalam tanda kurung, karena mesin semantik mungkin memperlakukan tanda kurung sebagai karakter literal, sehingga menghasilkan hasil yang kurang relevan.

    • Salah: (Show me datasets about US population by state)
    • Benar: Show me datasets about US population by state

  • Hindari menggabungkan hierarki boolean bertingkat yang kompleks dengan tanda kurung di dalam kolom bahasa alami. Penelusuran dioptimalkan untuk maksud bahasa alami. Membuat kueri terlalu rumit dengan tanda kurung dan blok logika eksplisit akan membingungkan parser.

    • Salah: (revenue data) AND system=BIGQUERY AND projectid:(data-warehouse | analytical-tier)
    • Benar: revenue data system=bigquery projectid:(data-warehouse|analytical-tier)

  • Jangan menambahkan spasi secara sembarangan kecuali jika spasi tersebut merupakan bagian dari nilai.

    • Salah: column:( email | id )
    • Benar: column:(email|id).

Langkah berikutnya