Bigtable: Read rows filter (#1253)

* read rows filter

* fix test case

* Filter

* add comments

* add espace for literal regex

* Fix failing test

* add snippet test

* Fix doc

* code review updates

* moved builder in to its own namespace

* add snippet test

* arrange use statement

* fix failing test case

* Fix documentation

Bigtable/src/Filter/Builder/FamilyFilter.php

@@ -0,0 +1,83 @@
+<?php
+/**
+ * Copyright 2018, Google LLC All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+namespace Google\Cloud\Bigtable\Filter\Builder;
+
+use Google\Cloud\Bigtable\Filter\SimpleFilter;
+use Google\Cloud\Bigtable\V2\RowFilter;
+
+/**
+ * A builder used to configure column family filters.
+ *
+ * Example:
+ * ```
+ * use Google\Cloud\Bigtable\Filter;
+ *
+ * $builder = Filter::family();
+ * ```
+ */
+class FamilyFilter
+{
+    use RegexTrait;
+
+    /**
+     * @var string
+     */
+    private static $regexSetter = 'setFamilyNameRegexFilter';
+
+    /**
+     * Matches only cells from columns whose families satisfy the given
+     * [RE2 regex](https://github.com/google/re2/wiki/Syntax).
+     * For technical reasons, the regex must not contain the `:` character, even
+     * if it is not being used as literal. Note that, since column families
+     * cannot contain the new line character `\n`, it is sufficient to use `.`
+     * as a full wildcard when matching column family names.
+     *
+     * Example:
+     * ```
+     * $familyFilter = $builder->regex('prefix.*');
+     * ```
+     *
+     * @param string $value A regex value.
+     * @return SimpleFilter
+     */
+    public function regex($value)
+    {
+        return $this->buildRegexFilter($value, self::$regexSetter);
+    }
+
+    /**
+     * Matches only cells from columns whose families match the value.
+     *
+     * Example:
+     * ```
+     * $familyFilter = $builder->exactMatch('cf1');
+     * ```
+     *
+     * @param string $value An exact value to match.
+     * @return SimpleFilter
+     * @throws \InvalidArgumentException When the provided value is not an array
+     *         or string.
+     */
+    public function exactMatch($value)
+    {
+        return $this->buildRegexFilter(
+            $this->escapeLiteralValue($value),
+            self::$regexSetter
+        );
+    }
+}

Bigtable/src/Filter/Builder/KeyFilter.php

@@ -0,0 +1,115 @@
+<?php
+/**
+ * Copyright 2018, Google LLC All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+namespace Google\Cloud\Bigtable\Filter\Builder;
+
+use Google\Cloud\Bigtable\Filter\SimpleFilter;
+use Google\Cloud\Bigtable\V2\RowFilter;
+
+/**
+ * A builder used to configure row key related filters.
+ *
+ * Example:
+ * ```
+ * use Google\Cloud\Bigtable\Filter;
+ *
+ * $builder = Filter::key();
+ * ```
+ */
+class KeyFilter
+{
+    use RegexTrait;
+
+    /**
+     * @var string
+     */
+    private static $regexSetter = 'setRowKeyRegexFilter';
+
+    /**
+     * Matches only cells from rows whose keys satisfy the given
+     * [RE2 regex](https://github.com/google/re2/wiki/Syntax). In other words,
+     * passes through the entire row when the key matches, and otherwise
+     * produces an empty row. Note that, since row keys can contain arbitrary
+     * bytes, the `\C` escape sequence must be used if a true wildcard is
+     * desired. The `.` character will not match the new line character `\n`,
+     * which may be present in a binary key.
+     *
+     * Example:
+     * ```
+     * $keyFilter = $builder->regex('prefix.*');
+     * ```
+     *
+     * @param string $value A regex value.
+     * @return SimpleFilter
+     */
+    public function regex($value)
+    {
+        return $this->buildRegexFilter($value, self::$regexSetter);
+    }
+
+    /**
+     * Matches only cells from rows whose keys equal the value. In other words,
+     * passes through the entire row when the key matches, and otherwise
+     * produces an empty row.
+     *
+     * Example:
+     * ```
+     * $keyFilter = $builder->exactMatch('r1');
+     * ```
+     *
+     * @param string $value An exact value.
+     * @return SimpleFilter
+     * @throws \InvalidArgumentException When the provided value is not an array
+     *         or string.
+     */
+    public function exactMatch($value)
+    {
+        return $this->buildRegexFilter(
+            $this->escapeLiteralValue($value),
+            self::$regexSetter
+        );
+    }
+
+    /**
+     * Matches all cells from a row with `probability`, and matches no cells
+     * from the row with probability 1-`probability`.
+     *
+     * Example:
+     * ```
+     * $keyFilter = $builder->sample(.7);
+     * ```
+     *
+     * @param float $probability The probability to filter by. Must be within
+     *        the range [0, 1], end points excluded.
+     * @return SimpleFilter
+     * @throws \InvalidArgumentException When the probability does not fall
+     *         within the acceptable range.
+     */
+    public function sample($probability)
+    {
+        if ($probability < 0) {
+            throw new \InvalidArgumentException('Probability must be positive');
+        }
+        if ($probability >= 1.0) {
+            throw new \InvalidArgumentException('Probability must be less than 1.0');
+        }
+
+        return new SimpleFilter(
+            (new RowFilter)->setRowSampleFilter($probability)
+        );
+    }
+}

Bigtable/src/Filter/Builder/LimitFilter.php

@@ -0,0 +1,79 @@
+<?php
+/**
+ * Copyright 2018, Google LLC All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+namespace Google\Cloud\Bigtable\Filter\Builder;
+
+use Google\Cloud\Bigtable\Filter\SimpleFilter;
+use Google\Cloud\Bigtable\V2\RowFilter;
+
+/**
+ * A builder used to configure limit based filters.
+ *
+ * Example:
+ * ```
+ * use Google\Cloud\Bigtable\Filter;
+ *
+ * $builder = Filter::limit();
+ * ```
+ */
+class LimitFilter
+{
+    /**
+     * Matches only the first N cells of each row. If duplicate cells are
+     * present, as is possible when using an
+     * {@see Google\Cloud\Bigtable\Filter\InterleaveFilter}, each copy of the
+     * cell is counted separately.
+     *
+     * Example:
+     * ```
+     * $limitFilter = $builder->cellsPerRow(2);
+     * ```
+     *
+     * @param int $count The number of cells to limit to.
+     * @return SimpleFilter
+     */
+    public function cellsPerRow($count)
+    {
+        return new SimpleFilter(
+            (new RowFilter)->setCellsPerRowLimitFilter($count)
+        );
+    }
+
+    /**
+     * Matches only the most recent N cells within each column. For
+     * example, if count=2, this filter would match column `foo:bar` at
+     * timestamps 10 and 9 skip all earlier cells in `foo:bar`, and then begin
+     * matching again in column `foo:bar2`. If duplicate cells are present, as
+     * is possible when using an
+     * {@see Google\Cloud\Bigtable\Filter\InterleaveFilter}, each copy of the
+     * cell is counted separately.
+     *
+     * Example:
+     * ```
+     * $limitFilter = $builder->cellsPerColumn(2);
+     * ```
+     *
+     * @param int $count The number of cells to limit to.
+     * @return SimpleFilter
+     */
+    public function cellsPerColumn($count)
+    {
+        return new SimpleFilter(
+            (new RowFilter)->setCellsPerColumnLimitFilter($count)
+        );
+    }
+}

Bigtable/src/Filter/Builder/OffsetFilter.php

@@ -0,0 +1,55 @@
+<?php
+/**
+ * Copyright 2018, Google LLC All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+namespace Google\Cloud\Bigtable\Filter\Builder;
+
+use Google\Cloud\Bigtable\Filter\SimpleFilter;
+use Google\Cloud\Bigtable\V2\RowFilter;
+
+/**
+ * A builder used to configure offset based filters.
+ *
+ * Example:
+ * ```
+ * use Google\Cloud\Bigtable\Filter;
+ *
+ * $builder = Filter::offset();
+ * ```
+ */
+class OffsetFilter
+{
+    /**
+     * Skips the first N cells of each row, matching all subsequent cells. If
+     * duplicate cells are present, as is possible when using an
+     * {@see Google\Cloud\Bigtable\Filter\InterleaveFilter}, each copy of the
+     * cell is counted separately.
+     *
+     * Example:
+     * ```
+     * $limitFilter = $builder->cellsPerRow(2);
+     * ```
+     *
+     * @param int $count The count to offset by.
+     * @return SimpleFilter
+     */
+    public function cellsPerRow($count)
+    {
+        return new SimpleFilter(
+            (new RowFilter)->setCellsPerRowOffsetFilter($count)
+        );
+    }
+}