Gunakan filter - Tablestore SDK untuk Python - Tablestore

Gunakan Tablestore SDK untuk Python guna memfilter baris berdasarkan nilai kolom atribut di sisi server dan mengurangi jumlah data yang dikembalikan ke klien.

Prasyarat

Instal Tablestore SDK untuk Python dan inisialisasi klien.

Deskripsi fungsi

Filter diterapkan setelah server membaca data. Hanya baris yang memenuhi kondisi yang dikembalikan ke klien. Pemfilteran tidak mengurangi jumlah baris yang dibaca oleh server atau CU baca yang dikonsumsi. Gunakan filter setelah Anda mempersempit rentang primary key.

Kondisi filter berikut ini didukung:

SingleColumnCondition membandingkan nilai satu kolom atribut.
SingleColumnRegexCondition mengekstraksi substring dari kolom atribut string dan membandingkan nilai yang diekstraksi.
CompositeColumnCondition menggabungkan hingga 32 kondisi dengan AND, OR, atau NOT.

Contoh berikut hanya mengembalikan baris yang nilai terbarunya pada kolom atribut status adalah online selama pembacaan rentang.

column_filter = SingleColumnCondition(
    "status",
    "online",
    ComparatorType.EQUAL,
    pass_if_missing=False,
)
start_primary_key = [("partition", "device"), ("id", INF_MIN)]
end_primary_key = [("partition", "device"), ("id", INF_MAX)]

consumed, next_start_primary_key, rows, next_token = client.get_range(
    "example_table",
    Direction.FORWARD,
    start_primary_key,
    end_primary_key,
    column_filter=column_filter,
)

Parameter

Kondisi nilai kolom tunggal

Panggil SingleColumnCondition(column_name, column_value, comparator, pass_if_missing=True, latest_version_only=True) untuk membuat kondisi nilai kolom tunggal.

Nama	Tipe	Deskripsi
column_name (wajib)	`str`	Nama kolom atribut yang akan dievaluasi.
column_value (wajib)	`str`, `int`, `bytes`, `float`, atau `bool`	Nilai target. Tipe datanya harus sesuai dengan tipe nilai kolom atribut.
comparator (wajib)	`ComparatorType`	Operator perbandingan. Nilai yang valid adalah `EQUAL`, `NOT_EQUAL`, `GREATER_THAN`, `GREATER_EQUAL`, `LESS_THAN`, dan `LESS_EQUAL`.
pass_if_missing (opsional)	`bool`	Menentukan apakah suatu baris lolos filter jika kolom atribut target tidak ada. Nilai default: `True`. Jika parameter ini `False`, baris tanpa kolom tersebut tidak dikembalikan.
latest_version_only (opsional)	`bool`	Menentukan apakah hanya versi terbaru yang dievaluasi. Nilai default: `True`. Jika parameter ini `False`, suatu baris lolos jika versi apa pun memenuhi kondisi.

Kondisi ekspresi reguler

Panggil SingleColumnRegexCondition(column_name, comparator, column_value=None, regex_rule=None, latest_version_only=True) untuk membuat kondisi ekspresi reguler. Hanya kolom atribut string yang mendukung pemfilteran ekspresi reguler.

Nama	Type	Deskripsi
column_name (wajib)	`str`	Nama kolom atribut string yang akan dievaluasi.
comparator (wajib)	`ComparatorType`	Operator perbandingan. Nilai yang valid adalah `EQUAL`, `NOT_EQUAL`, `GREATER_THAN`, `GREATER_EQUAL`, `LESS_THAN`, `LESS_EQUAL`, `EXIST`, dan `NOT_EXIST`.
column_value (opsional)	`str`, `int`, atau `float`	Nilai target. Abaikan parameter ini jika `comparator` bernilai `EXIST` atau `NOT_EXIST`. Jika tidak, parameter ini wajib diisi. Tipe datanya harus sesuai dengan `regex_rule.cast_type`.
regex_rule (opsional)	`RegexRule`	Aturan ekstraksi substring dan konversi tipe.
latest_version_only (opsional)	`bool`	Menentukan apakah hanya versi terbaru yang dievaluasi. Nilai default: `True`. Jika parameter ini `False`, suatu baris lolos jika versi apa pun memenuhi kondisi.

Jika kolom atribut target tidak ada, baris tersebut tidak akan lolos filter ekspresi reguler. Parameter pass_if_missing tidak dapat dikonfigurasi secara terpisah untuk kondisi ini.

Aturan ekspresi reguler

Parameter regex_rule bertipe RegexRule dan berisi parameter berikut.

Nama	Tipe	Deskripsi
regex_input (wajib)	`str`	Ekspresi reguler, maksimal 256 byte. Ekspresi yang kompatibel dengan Perl dan karakter single-byte didukung. Karakter Tionghoa tidak didukung. Jika ekspresi berisi capturing groups, grup pertama yang diekstraksi. Jika tidak, seluruh kecocokan (match) yang diekstraksi.
cast_type (wajib)	`CastType`	Tipe data tujuan konversi nilai yang diekstraksi. Nilai yang valid adalah `VT_STRING`, `VT_INTEGER`, dan `VT_DOUBLE`. Baris yang nilainya tidak dapat dikonversi tidak lolos filter.

Kondisi komposit

Panggil CompositeColumnCondition(combinator) untuk membuat kondisi komposit, lalu panggil add_sub_condition untuk menambahkan kondisi.

Nama	Tipe	Deskripsi
combinator (wajib)	`LogicalOperator`	Operator logika. Nilai yang valid adalah `AND`, `OR`, dan `NOT`.
sub_conditions (wajib)	`List[ColumnCondition]`	Kondisi yang akan digabungkan. Kondisi nilai kolom tunggal, kondisi ekspresi reguler, dan kondisi komposit bersarang didukung, dengan maksimal 32 kondisi.

Contoh

Filter dengan ekspresi reguler

Contoh berikut mengekstraksi angka dari nilai seperti user_004 pada kolom atribut account, mengonversi angka tersebut menjadi integer, dan hanya mengembalikan baris yang nilainya lebih besar dari 3.

regex_rule = RegexRule(r"user_(\d+)", CastType.VT_INTEGER)
column_filter = SingleColumnRegexCondition(
    "account",
    ComparatorType.GREATER_THAN,
    3,
    regex_rule,
)

consumed, next_start_primary_key, rows, next_token = client.get_range(
    "example_table",
    Direction.FORWARD,
    start_primary_key,
    end_primary_key,
    column_filter=column_filter,
)

Gabungkan filter

Contoh berikut membangun filter (category == "sensor" OR category == "gateway") AND score > 3.

category_filter = CompositeColumnCondition(LogicalOperator.OR)
category_filter.add_sub_condition(
    SingleColumnCondition("category", "sensor", ComparatorType.EQUAL)
)
category_filter.add_sub_condition(
    SingleColumnCondition("category", "gateway", ComparatorType.EQUAL)
)

column_filter = CompositeColumnCondition(LogicalOperator.AND)
column_filter.add_sub_condition(category_filter)
column_filter.add_sub_condition(
    SingleColumnCondition("score", 3, ComparatorType.GREATER_THAN)
)

Evaluasi versi historis

Contoh berikut mengatur latest_version_only menjadi False. Suatu baris dikembalikan jika versi apa pun dari kolom atribut status bernilai online. Baris yang tidak memiliki kolom status tidak dikembalikan.

column_filter = SingleColumnCondition(
    "status",
    "online",
    ComparatorType.EQUAL,
    pass_if_missing=False,
    latest_version_only=False,
)