feat: Add configurable page-size parameter to `fga tuple read` command #571

Siddhant-K-code · 2025-08-25T17:31:44Z

Description

This PR enhances the fga tuple read command by adding support for a configurable page-size parameter and implementing intelligent default page-size behavior based on the max-pages setting to improve performance when reading tuples.

Related Issue

Fixes #568

Changes made

Added --page-size flag to the fga tuple read command
Implemented smart default page-size logic:
- When max-pages=0 (read all tuples): defaults to 100 for better efficiency
- When max-pages!=0 (limited pages): defaults to 50 to maintain backward compatibility
- When --page-size is explicitly specified: uses the provided value
Updated internal tuple.Read function to accept page size as a parameter
Updated cmd/store/export.go to use the appropriate page size
Added comprehensive unit tests for the new page-size behavior

Command usage examples

1. Read all tuples (optimized with page-size=100)

Command:

fga tuple read --store-id=01H0H015178Y2V4CX10C2KGHF4 --max-pages=0

Output:

{
  "tuples": [
    {
      "key": {
        "user": "user:anne",
        "relation": "reader",
        "object": "document:roadmap"
      },
      "timestamp": "2024-01-15T10:30:00Z"
    },
    {
      "key": {
        "user": "user:bob",
        "relation": "writer",
        "object": "document:design"
      },
      "timestamp": "2024-01-15T10:31:00Z"
    }
    // ... fetches up to 100 tuples per page instead of 50
  ],
  "continuation_token": ""
}

2. Read with limited pages (default page-size=50)

Command:

fga tuple read --store-id=01H0H015178Y2V4CX10C2KGHF4 --max-pages=2 --user user:anne

Output:

{
  "tuples": [
    {
      "key": {
        "user": "user:anne",
        "relation": "reader",
        "object": "document:roadmap"
      },
      "timestamp": "2024-01-15T10:30:00Z"
    },
    {
      "key": {
        "user": "user:anne",
        "relation": "viewer",
        "object": "folder:projects"
      },
      "timestamp": "2024-01-15T10:32:00Z"
    }
    // ... up to 50 tuples per page (maintains backward compatibility)
  ],
  "continuation_token": ""
}

3. Read with custom page size

Command:

fga tuple read --store-id=01H0H015178Y2V4CX10C2KGHF4 --max-pages=3 --page-size=75 --relation viewer

Output:

{
  "tuples": [
    {
      "key": {
        "user": "user:anne",
        "relation": "viewer",
        "object": "folder:projects"
      },
      "timestamp": "2024-01-15T10:32:00Z"
    },
    {
      "key": {
        "user": "user:bob",
        "relation": "viewer",
        "object": "folder:shared"
      },
      "timestamp": "2024-01-15T10:33:00Z"
    }
    // ... fetches up to 75 tuples per page as specified
  ],
  "continuation_token": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTUUoyN01MdTdqTjh0Ym42MjA4In0="
}

4. Help output showing new flag

Command:

fga tuple read --help

Output (relevant section):

Flags:
  -h, --help                 help for read
      --max-pages int        Max number of pages to get. Set to 0 to get all pages. (default 20)
      --object string        Object
      --output-format string Specifies the format for data presentation. Valid options: json, simple-json, csv, and yaml. (default "json")
      --page-size int32      Number of tuples to return per page. Defaults to 100 when max-pages=0, or 50 otherwise. Max is 100.
      --relation string      Relation
      --user string          User
      --consistency string   Consistency preference for the request. Valid options are HIGHER_CONSISTENCY and MINIMIZE_LATENCY.

Performance Impact

For stores with many tuples, this change significantly reduces API calls when reading all tuples:

Scenario	Before (page-size=50)	After (page-size=100)	Improvement
100 tuples	2 API calls	1 API call	50% reduction
500 tuples	10 API calls	5 API calls	50% reduction
1000 tuples	20 API calls	10 API calls	50% reduction
5000 tuples	100 API calls	50 API calls	50% reduction

No breaking changes

This PR does not include breaking changes.

The default behavior when max-pages!=0 remains unchanged (page-size=50), ensuring complete backward compatibility.

Summary by CodeRabbit

New Features
- Added a --page-size flag to the tuple read command, allowing users to control how many results are returned per page.
- Introduced smart defaults when --page-size is not provided: 100 when no max page limit is set, and 50 when a max page limit is specified.
- Improves pagination control and performance predictability when reading large sets of tuples.

coderabbitai · 2025-08-25T17:31:53Z

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Walkthrough

Adds page-size support to tuple reads: introduces a --page-size flag, updates defaulting logic (100 when max-pages=0, else 50), threads pageSize through the CLI to internal tuple.Read, and updates the tuple.Read signature to accept pageSize. Also updates a store export call-site to pass an explicit default page size.

Changes

Cohort / File(s)	Summary
Tuple read command and internal API `cmd/tuple/read.go`, `internal/tuple/read.go`	Add pageSize parameter to tuple.Read; introduce --page-size flag; implement defaulting: pageSize=100 when max-pages=0, else 50; propagate pageSize to SDK read options.
Tuple read tests `cmd/tuple/read_test.go`	Update tests to pass/verify pageSize; add tests for defaulting behavior and custom page size.
Store export call-site update `cmd/store/export.go`	Update tuple.Read invocation to include explicit page size (tuple.DefaultReadPageSize) per new function signature.

Sequence Diagram(s)

sequenceDiagram
    autonumber
    actor U as User
    participant CLI as fga tuple read (CLI)
    participant Resolver as PageSize Resolver
    participant T as internal/tuple.Read
    participant SDK as OpenFGA SDK

    U->>CLI: run "fga tuple read [--max-pages N] [--page-size P]"
    CLI->>Resolver: compute pageSize (N, P)
    alt P provided (>0)
        Note right of Resolver: Use P
    else P not provided (0)
        alt N == 0
            Note right of Resolver: pageSize = 100
        else N > 0
            Note right of Resolver: pageSize = 50
        end
    end
    Resolver-->>CLI: pageSize
    CLI->>T: Read(ctx, req, maxPages=N, pageSize, consistency)
    T->>SDK: Read(req, options{PageSize: pageSize}, paging)
    SDK-->>T: tuples (+continuation)
    T-->>CLI: aggregated response
    CLI-->>U: output tuples

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Assessment against linked issues

Objective	Addressed	Explanation
Default page-size = 100 when max-pages=0 (#568)	✅
Default page-size = 50 when max-pages!=0 (#568)	✅
Allow specifying page-size parameter; always honor it when provided (#568)	✅

Assessment against linked issues: Out-of-scope changes

Code Change	Explanation
Pass explicit default page size to tuple.Read in store export flow (cmd/store/export.go, exact lines not provided)	Not related to tuple read CLI behavior in #568; modifies store export path which isn’t mentioned in the issue. Line numbers unavailable in provided summary.

Suggested labels

codex

Suggested reviewers

rhamzeh

✨ Finishing Touches

🧪 Generate unit tests

Create PR with unit tests
Post copyable unit tests in a comment

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

Review comments: Directly reply to a review comment made by CodeRabbit. Example:
- I pushed a fix in commit <commit_id>, please review it.
- Open a follow-up GitHub issue for this discussion.
Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query.
PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
- @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
- @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

CodeRabbit Commands (Invoked using PR/Issue comments)

Type @coderabbitai help to get the list of available commands.

Other keywords and placeholders

Add @coderabbitai ignore or @coderabbit ignore anywhere in the PR description to prevent this PR from being reviewed.
Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (`.coderabbit.yaml`)

You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
Please see the configuration documentation for more information.
If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Status, Documentation and Community

Visit our Status Page to check the current availability of CodeRabbit.
Visit our Documentation for detailed information on how to use CodeRabbit.
Join our Discord Community to get help, request features, and share feedback.
Follow us on X/Twitter for updates and announcements.

rhamzeh

Also would you mind updating the read section in the README?

cmd/tuple/read.go

rhamzeh · 2025-09-04T18:37:02Z

Thanks!

feat: Add configurable page-size parameter to fga tuple read command

a92a10a

Siddhant-K-code requested a review from a team as a code owner August 25, 2025 17:31

Siddhant-K-code added 2 commits August 25, 2025 17:34

lint fix

56998ed

add changelog entry

991a77d

This comment was marked as resolved.

Sign in to view

Siddhant-K-code added 3 commits August 25, 2025 17:53

better err handling

51d3cd3

fix lint

2cad23e

fix lint

1e96862

rhamzeh reviewed Sep 4, 2025

View reviewed changes

cmd/tuple/read.go Outdated Show resolved Hide resolved

addressing review comments

56c4752

Siddhant-K-code requested review from a team as code owners September 4, 2025 17:05

Siddhant-K-code added 3 commits September 4, 2025 17:06

update test to use DefaultReadPageSize for max-pages non-zero case

515ba10

gofmt

e27e357

fmt

5de5a89

Siddhant-K-code force-pushed the fix/568 branch from 28bab45 to 5de5a89 Compare September 4, 2025 17:22

Siddhant-K-code requested a review from rhamzeh September 4, 2025 17:33

rhamzeh approved these changes Sep 4, 2025

View reviewed changes

rhamzeh added this pull request to the merge queue Sep 4, 2025

Merged via the queue into openfga:main with commit b905f4d Sep 4, 2025
19 checks passed

Siddhant-K-code deleted the fix/568 branch September 4, 2025 20:05

rhamzeh mentioned this pull request Oct 8, 2025

release: v0.7.5 #587

Merged

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: Add configurable page-size parameter to `fga tuple read` command #571

feat: Add configurable page-size parameter to `fga tuple read` command #571

Uh oh!

Siddhant-K-code commented Aug 25, 2025 •

edited by coderabbitai bot

Loading

Uh oh!

coderabbitai bot commented Aug 25, 2025 •

edited

Loading

Review skipped

Chat

Support

CodeRabbit Commands (Invoked using PR/Issue comments)

Other keywords and placeholders

CodeRabbit Configuration File (`.coderabbit.yaml`)

Status, Documentation and Community

Uh oh!

This comment was marked as resolved.

Uh oh!

rhamzeh left a comment

Uh oh!

Uh oh!

rhamzeh commented Sep 4, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat: Add configurable page-size parameter to fga tuple read command #571

feat: Add configurable page-size parameter to fga tuple read command #571

Uh oh!

Conversation

Siddhant-K-code commented Aug 25, 2025 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related Issue

Changes made

Command usage examples

1. Read all tuples (optimized with page-size=100)

2. Read with limited pages (default page-size=50)

3. Read with custom page size

4. Help output showing new flag

Performance Impact

No breaking changes

Summary by CodeRabbit

Uh oh!

coderabbitai bot commented Aug 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Assessment against linked issues

Assessment against linked issues: Out-of-scope changes

Suggested labels

Suggested reviewers

Chat

Support

CodeRabbit Commands (Invoked using PR/Issue comments)

Other keywords and placeholders

CodeRabbit Configuration File (.coderabbit.yaml)

Status, Documentation and Community

Uh oh!

This comment was marked as resolved.

Uh oh!

rhamzeh left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rhamzeh commented Sep 4, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat: Add configurable page-size parameter to `fga tuple read` command #571

feat: Add configurable page-size parameter to `fga tuple read` command #571

Siddhant-K-code commented Aug 25, 2025 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Aug 25, 2025 •

edited

Loading

CodeRabbit Configuration File (`.coderabbit.yaml`)