Filter - Tablestore SDK for Java - Tablestore - Alibaba Cloud Documentation Center

Tablestore SDK for Java memfilter baris berdasarkan nilai kolom atau mengembalikan sebagian Kolom atribut di sisi server guna mengurangi volume data yang ditransfer ke klien.

Prasyarat

Pasang Tablestore SDK for Java dan inisialisasi klien.

Deskripsi

Filter dijalankan di server setelah setiap baris dibaca dan hanya mengembalikan baris yang memenuhi kriteria Anda. Karena pemfilteran terjadi setelah pembacaan, filter ini tidak mengurangi jumlah baris yang dipindai, melainkan mengurangi volume data yang dikirim melalui jaringan.

Tetapkan filter dengan memanggil setFilter pada SingleRowQueryCriteria, RangeRowQueryCriteria, MultiRowQueryCriteria, atau RangeIteratorParameter. Jenis filter berikut tersedia:

SingleColumnValueFilter: membandingkan nilai satu kolom properti dengan nilai target menggunakan operator relasional.
SingleColumnValueRegexFilter: mengekstraksi substring dari kolom properti bertipe String menggunakan ekspresi reguler, mengonversinya ke tipe target, lalu membandingkannya dengan nilai target.
CompositeColumnValueFilter: menggabungkan beberapa filter menggunakan Operator logika (AND, OR, atau NOT). Filter komposit mendukung hingga 32 sub-kondisi.
ColumnPaginationFilter: mengembalikan Kolom atribut berdasarkan offset dan batas tanpa mengevaluasi nilai kolom.

new SingleColumnValueFilter(columnName, operator, columnValue)
new SingleColumnValueRegexFilter(columnName, regexRule, operator, columnValue)
new CompositeColumnValueFilter(logicOperator)
new ColumnPaginationFilter(limit, offset)

Contoh berikut membaca baris dari tabel filter_demo di mana kolom col1 sama dengan val1 menggunakan SingleColumnValueFilter.

RangeRowQueryCriteria criteria = new RangeRowQueryCriteria("filter_demo");

PrimaryKeyBuilder startBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
startBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
criteria.setInclusiveStartPrimaryKey(startBuilder.build());

PrimaryKeyBuilder endBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
endBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
criteria.setExclusiveEndPrimaryKey(endBuilder.build());

criteria.setMaxVersions(1);

// Bangun filter: col1 == "val1"
SingleColumnValueFilter filter = new SingleColumnValueFilter(
        "col1",
        SingleColumnValueFilter.CompareOperator.EQUAL,
        ColumnValue.fromString("val1"));
criteria.setFilter(filter);

GetRangeResponse response = client.getRange(new GetRangeRequest(criteria));
System.out.println("Baris yang sesuai: " + response.getRows().size());

Parameter

Filter nilai kolom tunggal

Konstruktor SingleColumnValueFilter memiliki parameter berikut.

Nama	Tipe	Deskripsi
columnName (wajib)	String	Nama kolom properti yang akan dievaluasi.
operator (wajib)	CompareOperator	Operator relasional. Nilai yang valid: `EQUAL` (sama dengan) `NOT_EQUAL` (tidak sama dengan) `GREATER_THAN` (lebih besar dari) `GREATER_EQUAL` (lebih besar dari atau sama dengan) `LESS_THAN` (lebih kecil dari) `LESS_EQUAL` (lebih kecil dari atau sama dengan)
columnValue (wajib)	ColumnValue	Nilai yang digunakan dalam perbandingan.
passIfMissing (opsional)	boolean	Apakah baris yang tidak berisi kolom target harus dikembalikan. Nilai default `true`: baris tersebut dikembalikan. Atur ke `false` untuk mengecualikan baris yang tidak berisi kolom target.
latestVersionsOnly (opsional)	boolean	Apakah hanya versi terbaru dari kolom yang dievaluasi. Nilai default `true`: hanya versi terbaru yang dievaluasi. Atur ke `false` untuk mengembalikan baris jika ada versi apa pun yang memenuhi kondisi.

Filter ekspresi reguler

Konstruktor SingleColumnValueRegexFilter memiliki parameter berikut. Jika Anda menentukan aturan regex, kolom atribut target harus bertipe String.

Nama	Tipe	Deskripsi
columnName (wajib)	String	Nama kolom atribut yang akan dievaluasi. Jika `regexRule` ditentukan, kolom harus bertipe `String`.
regexRule (opsional)	RegexRule	Aturan pencocokan regex. Jika ditentukan, filter mengekstraksi substring dari nilai kolom string, mengonversi substring tersebut, lalu mengevaluasinya. Jika diabaikan, filter mengevaluasi nilai kolom asli. Aturan ini memiliki parameter berikut: `regex`: ekspresi reguler yang mencocokkan substring. Panjang maksimum: 256 byte. Mendukung ekspresi reguler single-byte yang kompatibel dengan Perl; tidak mencocokkan karakter Tionghoa. Mendukung capturing groups — ketika ekspresi berisi grup, regex mengembalikan substring pertama yang cocok. Misalnya, jika nilai kolom adalah `1aaa51bbb5` dan regex-nya adalah `1([a-z]+)5`, substring yang dikembalikan adalah `aaa`. `castType`: tipe tujuan untuk mengonversi substring yang cocok. Nilai yang valid: `VT_INTEGER` (integer), `VT_DOUBLE` (floating point presisi ganda), dan `VT_STRING` (string).
operator (wajib)	CompareOperator	Operator evaluasi. Nilai yang valid: `EQUAL`, `NOT_EQUAL`, `GREATER_THAN`, `GREATER_EQUAL`, `LESS_THAN`, `LESS_EQUAL`, `EXIST`, dan `NOT_EXIST`.
columnValue (opsional)	ColumnValue	Nilai perbandingan. Parameter ini wajib untuk keenam operator relasional dan harus diabaikan untuk `EXIST` dan `NOT_EXIST`. Jika `regexRule` ditentukan, tipe nilai harus sesuai dengan `castType`.
latestVersionsOnly (opsional)	boolean	Menentukan apakah hanya versi terbaru dari kolom atribut yang dievaluasi. Nilai default: `true`. Jika diatur ke `false`, baris dikembalikan jika ada versi apa pun yang cocok.

Filter komposit

Konstruktor dan daftar sub-filter CompositeColumnValueFilter memiliki parameter berikut. Tambahkan sub-filter dengan memanggil addFilter(). Filter komposit mendukung hingga 32 sub-kondisi.

Nama

Tipe

Deskripsi

type (wajib)

LogicOperator

Operator logika. Nilai yang valid:

AND (logika AND). Tambahkan minimal dua sub-filter.
OR (logika OR). Tambahkan minimal dua sub-filter.
NOT (logika NOT). Tambahkan tepat satu sub-filter.

filters (wajib)

List<ColumnValueFilter>

Sub-filter yang digabungkan oleh operator logika. Tambahkan setiap sub-filter dengan addFilter(). Sub-filter dapat berupa SingleColumnValueFilter, SingleColumnValueRegexFilter, atau CompositeColumnValueFilter lain (mendukung nesting).

Filter pagination kolom atribut

Konstruktor ColumnPaginationFilter memiliki parameter berikut. Jika offset diabaikan, nilai default-nya adalah 0.

Nama	Tipe	Deskripsi
limit (wajib)	int	Jumlah Kolom atribut yang dikembalikan. Nilainya harus lebih besar dari 0.
offset (opsional)	int	Offset berbasis nol dari Kolom atribut pertama yang dikembalikan. Nilainya harus lebih besar dari atau sama dengan 0. Nilai default: `0`.

Contoh

Bandingkan substring yang diekstraksi dengan ekspresi reguler

Gunakan RegexRule untuk mengekstraksi substring dari nilai kolom, lalu bandingkan substring tersebut dengan nilai target. Contoh berikut menerapkan regex 1([a-z]+)5 pada col2, menangkap grup pertama, lalu membandingkannya dengan string aaa.

RangeRowQueryCriteria criteria = new RangeRowQueryCriteria("filter_demo");

PrimaryKeyBuilder startBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
startBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
criteria.setInclusiveStartPrimaryKey(startBuilder.build());

PrimaryKeyBuilder endBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
endBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
criteria.setExclusiveEndPrimaryKey(endBuilder.build());

criteria.setMaxVersions(1);

// Regex "1([a-z]+)5" menangkap grup pertama; castType=VT_STRING membandingkan hasil sebagai string.
RegexRule regexRule = new RegexRule("1([a-z]+)5", RegexRule.CastType.VT_STRING);
SingleColumnValueRegexFilter filter = new SingleColumnValueRegexFilter(
        "col2",
        regexRule,
        SingleColumnValueRegexFilter.CompareOperator.EQUAL,
        ColumnValue.fromString("aaa"));
criteria.setFilter(filter);

GetRangeResponse response = client.getRange(new GetRangeRequest(criteria));
System.out.println("Baris yang sesuai: " + response.getRows().size());

Gabungkan beberapa filter dengan operator logika

Gunakan CompositeColumnValueFilter untuk menggabungkan beberapa filter dengan operator logika. Filter komposit dapat disarangkan. Contoh berikut membangun kondisi (col1 == "val1" OR cast<String>(reg(col2)) >= "aaa") AND col3 == "val3".

RangeRowQueryCriteria criteria = new RangeRowQueryCriteria("filter_demo");

PrimaryKeyBuilder startBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
startBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
criteria.setInclusiveStartPrimaryKey(startBuilder.build());

PrimaryKeyBuilder endBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
endBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
criteria.setExclusiveEndPrimaryKey(endBuilder.build());

criteria.setMaxVersions(1);

// Leaf 1: col1 == "val1"
SingleColumnValueFilter leaf1 = new SingleColumnValueFilter(
        "col1",
        SingleColumnValueFilter.CompareOperator.EQUAL,
        ColumnValue.fromString("val1"));

// Leaf 2: cast<String>(reg(col2)) >= "aaa"
RegexRule regexRule = new RegexRule("1([a-z]+)5", RegexRule.CastType.VT_STRING);
SingleColumnValueRegexFilter leaf2 = new SingleColumnValueRegexFilter(
        "col2",
        regexRule,
        SingleColumnValueRegexFilter.CompareOperator.GREATER_EQUAL,
        ColumnValue.fromString("aaa"));

// Kombinasi OR: leaf1 OR leaf2
CompositeColumnValueFilter orFilter = new CompositeColumnValueFilter(
        CompositeColumnValueFilter.LogicOperator.OR);
orFilter.addFilter(leaf1);
orFilter.addFilter(leaf2);

// Leaf 3: col3 == "val3"
SingleColumnValueFilter leaf3 = new SingleColumnValueFilter(
        "col3",
        SingleColumnValueFilter.CompareOperator.EQUAL,
        ColumnValue.fromString("val3"));

// Kombinasi AND: (leaf1 OR leaf2) AND leaf3
CompositeColumnValueFilter andFilter = new CompositeColumnValueFilter(
        CompositeColumnValueFilter.LogicOperator.AND);
andFilter.addFilter(orFilter);
andFilter.addFilter(leaf3);

criteria.setFilter(andFilter);

GetRangeResponse response = client.getRange(new GetRangeRequest(criteria));
System.out.println("Baris yang sesuai: " + response.getRows().size());

Kontrol evaluasi kolom yang tidak ada dan versi historis

Gunakan setPassIfMissing untuk mengontrol apakah baris yang tidak berisi kolom target dikembalikan, dan setLatestVersionsOnly untuk mengontrol apakah versi historis juga dievaluasi.

SingleColumnValueFilter filter = new SingleColumnValueFilter(
        "col1",
        SingleColumnValueFilter.CompareOperator.EQUAL,
        ColumnValue.fromString("val1"));

// Lewati baris yang tidak berisi col1 (default: sertakan baris tersebut).
filter.setPassIfMissing(false);
// Evaluasi semua versi; kembalikan baris jika ada versi apa pun yang cocok (default: evaluasi hanya versi terbaru).
filter.setLatestVersionsOnly(false);

criteria.setFilter(filter);

Kembalikan halaman Kolom atribut

Gunakan ColumnPaginationFilter untuk mengembalikan jumlah Kolom atribut tertentu mulai dari offset tertentu. Contoh berikut melewati Kolom atribut pertama dan mengembalikan dua kolom berikutnya.

PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"))
        .build();

SingleRowQueryCriteria criteria = new SingleRowQueryCriteria("filter_demo", primaryKey);
criteria.setMaxVersions(1);
criteria.setFilter(new ColumnPaginationFilter(2, 1));

GetRowResponse response = client.getRow(new GetRowRequest(criteria));
for (Column column : response.getRow().getColumns()) {
    System.out.println(column.getName());
}