docs: expand RequestOptions.vf() with vf_ wire-format rules - #1840
Open
jacalata wants to merge 9 commits into
Open
docs: expand RequestOptions.vf() with vf_ wire-format rules#1840jacalata wants to merge 9 commits into
jacalata wants to merge 9 commits into
Conversation
The vf_ view filter has several server-side quirks that aren't obvious from the current one-line docstring. Document what values actually mean on the wire: exact match by default, comma as OR-list, backslash-escape for literal comma, empty-value override behavior, no wildcards, no operators, boolean 'true'/'false' only. This surfaces the behavior verified end-to-end against Tableau Cloud while working through --filter parsing issues in tabcmd, so callers who build vf_ requests through TSC know what the server will accept without having to reverse-engineer it. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The `filter=` list-endpoint syntax is unrelated to view-filter export requests (it's for querying lists of workbooks/users/etc). Steering readers there was scope creep. Just say ranges/operators aren't supported and point at workbook-side design. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Empirically verified: '\' in a vf_ value is the escape character. To
match a literal backslash you must double it ('\\'). Consolidate the
comma-escape and backslash rules into a single "backslash escapes"
bullet, since it's one mechanism.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Dropped the abstract "\c means literal c" phrasing (weird to read with a random letter) and led with the two concrete cases -- escape a comma, escape a backslash -- and noted why each escape matters (comma would otherwise start an OR-list; backslash otherwise consumed as escape). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Empirically tested 20+ candidate metacharacters (/ % + : ; { } [ ] ( )
? # * @ = & " ' < >) against a live server; every one passes through
untouched when URL-encoded. Only ',' and '\' are vf_ metacharacters
that need escaping in the wire value. Explicitly call that out so
readers don't assume everything URL-special needs a client-side
workaround.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
jacalata
enabled auto-merge (squash)
August 6, 2026 21:23
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Expands the RequestOptions.vf() docstring to more thoroughly document Tableau REST view-filter (vf_) query semantics.
Changes:
- Adds detailed
vf_<name>=<value>serialization and parsing rules (OR-lists, escaping, empty value behavior). - Clarifies unsupported patterns (wildcards, range/comparison operators) and boolean value constraints.
- Improves formatting and provides a direct link to Tableau REST filtering documentation.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+355
to
+357
| Serialized to the REST API as ``vf_<name>=<value>``. The rules below | ||
| describe how the server interprets the wire value; ``vf()`` itself | ||
| does not transform your input. |
Comment on lines
+368
to
+370
| quotes, brackets, etc.) pass through untouched -- ``vf()`` URL- | ||
| encodes them for transport and the server treats them as literal | ||
| data. To match a value containing a literal comma, escape it: |
Comment on lines
+376
to
+378
| - **Empty value** (``vf_<name>=``) overrides any workbook-embedded | ||
| filter on that column, effectively widening it to all values. | ||
| This is undocumented but stable behavior that some users rely on. |
Copilot flagged the vf() docstring as internally inconsistent: it said 'vf() does not transform your input' and later 'vf() URL-encodes them for transport' -- both true, but confusing side-by-side. Rewrite to distinguish (a) no Tableau-specific escaping/semantic transforms (b) percent-encoding for HTTP transport. Also fold in a note that percent-encoding is transport-layer only: %2C reaches the server as ',' and gets processed as a comma delimiter, so URL-encoding does NOT escape a literal comma or backslash. Also softened the 'empty value' bullet from 'undocumented but stable behavior' (reads as a compat promise the library can't make) to 'observed... may change without notice.' No behavior change.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.
Suppressed comments (1)
tableauserverclient/server/request_options.py:359
- The docstring says
vf()“only percent-encodes the value for HTTP transport”, butvf()just appends(name, value)toself.view_filtersand does not perform any encoding. Query-string percent-encoding (when it happens) is done later by the HTTP client/request construction, so attributing it tovf()is misleading and can be incorrect for code paths that build URLs manually.
Serialized to the REST API as ``vf_<name>=<value>``. The rules below
describe how the server interprets the wire value. ``vf()`` itself
does not apply any Tableau-specific escaping or semantic transforms
to your value; it only percent-encodes the value for HTTP transport,
which the server decodes back before applying the rules below.
Fresh-eyes review noted two nits on the expanded docstring: - The percent-encoding-does-not-escape claim (that %2C/%5C reach the server as literal comma/backslash and are then processed by the escaping rules like any other) is not on the public REST API doc page -- it was verified end-to-end against Tableau Cloud. Mark it as empirical with a verification date so a future maintainer knows to re-check if the wire behavior changes. Note that only the \, escape is documented; \ and the percent-encoding claim are empirical. - The wildcard note previously suggested "use .parameter() and design the workbook accordingly" as a workaround. That conflates two mechanisms (workbook filter controls' wildcard behavior vs. parameters) and doesn't cleanly work around vf_'s exact-match limit. Reworded to just state the fact: vf_ is exact-match / OR-list only, no contains/starts-with/ends-with. Docstring-only change; 41 request_option tests still pass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Previous wording said wildcards, ranges, and operators are "NOT supported" -- but I don't have live verification that `*` or `%` are inert in a vf_ value. The public filtering docs describe only exact match and OR-lists; behavior of other characters is undocumented, not verifiably absent. Rephrase to say what we know (docs don't cover it, TSC doesn't emit operator prefixes) and tell callers to verify against their target server before relying on the outcome. This is intentionally less prescriptive than the previous version. The related open PR #1854 was flagged by the same fresh-eyes pass for making an unverified `*`-as-wildcard claim in the opposite direction -- both PRs should stay in "docs describe X; other behaviors are untested" territory until we run the experiments. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The prior wording ('not documented, verify against your target') was
correct but weakly stated. Ran the actual experiments against Tableau
Server 3.30: vf_ passes * and % through as literal data, so a value of
'Widget*' matches only a product literally named 'Widget*', 'META
/star*/' matches its one row, and '*' or '%' on their own return zero
rows. Docstring now states that outcome directly and cites the
verification date.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The
vf_REST view filter has several server-side quirks that aren't obvious from the current one-linevf()docstring. This expands it to document what values actually mean on the wire: exact-match by default,,as OR-list,\,for a literal comma, the empty-value override behavior, no wildcards, no operators, boolean'true'/'false'only.Callers who build
vf_requests through TSC no longer have to reverse-engineer server behavior to figure out why their filter returned zero rows.Why now
Working through
--filterparsing bugs in tabcmd, I verified the wire-format behavior end-to-end against Tableau Cloud. Recording those findings in the library the tabcmd (and other callers) build on top of, so the next person doesn't have to redo the experiment.Notable server-side behaviors documented:
Rock\, Paper\, Scissors— backslash-escape works for a literal comma.%2Cdoes NOT.vf_Region=(empty value) — overrides any workbook-embedded filter on that column. Undocumented but stable and useful.*— NOT a wildcard onvf_. It's a wildcard on thefilter=list-endpoint syntax, which is a different query parameter.Test plan
help(PDFRequestOptions.vf)renders the expanded docstring cleanly🤖 Generated with Claude Code