6

What is a 'paged' call?

It is mentioned all over this page https://developers.google.com/apps-script/reference/gmail/gmail-app.html#search(String)

Is there any documentation of what a 'paged' call is? Why do they refer to it like it is something I should be able to read about somewhere else?

It says seven times

please use the 'paged' call, and specify ranges of the threads to retrieve in each call.

I understand the concept of breaking it into pieces but they are saying the 'paged' call is there some documentation on this or some sort of slang I am supposed to understand?

Rubén
  • 34,714
  • 9
  • 70
  • 166
CodeCamper
  • 6,609
  • 6
  • 44
  • 94
  • Look [here](https://stackoverflow.com/questions/55722600/how-to-read-all-mails-from-inbox-in-google-script) – Cooper Nov 20 '19 at 21:02
  • @Cooper Yes I saw that question, which is actually what prompted me to ask this question, because I never noticed the documentation in 7 places on one page mentions this phrase. Is there an official definition of what a 'paged' call is somewhere? Is this just some sort of programmer slang I am supposed to know about or is there some references online to what exactly `THE 'paged' call` is? – CodeCamper Nov 20 '19 at 21:03
  • Use the search for duplicate questions and search with `[google-apps-script] 'paged' call` – Cooper Nov 20 '19 at 21:03
  • 2
    A lot of times you have to use page tokens when searching through collections and I think that's what they're talking about. I didn't know what was either. – Cooper Nov 20 '19 at 21:05
  • @Cooper yes this is how I came about to asking this question, I know it is mentioned in many questions but no one ever defines what exactly a 'paged' call is? I mean I get the concept of how to solve those particular issues, but they are talking about it like it is some sort of official thing, so I guess the question is this just a figure of speech `programmer slang` or is there actually documentation somewhere anywhere of what a `paged call` is, maybe there is a paged call function we don't know about or maybe I can find paged call on slang dictionary. – CodeCamper Nov 20 '19 at 21:05
  • @Cooper right, I feel like when reading the documentation and you see something official like this, it is talking about something you would expect there to be a paragraph explaining what it is the concept and maybe examples of what paged calls are, because it makes me think there is a paged call function somewhere. – CodeCamper Nov 20 '19 at 21:08
  • For a code example showing a paged call, see https://stackoverflow.com/a/55723614/771768 – Carl Walsh Jun 04 '23 at 15:51

2 Answers2

2

This is referring to the concept of a Page Token, you should be able to add it as a parameter to your requests. There's some better examples here. Unfortunately, there's no page that really explains what a page token is so I'll try my best.

Let's say I call the Gmail API and I want a list of all emails in my account. That's too much to deliver in one request, so I ask for 1,000 at a time, starting from my most recent messages. When I request 1,000 messages, Google will return a page token to me along with the 1,000 results I asked for. If I want the 1,000 next most recent emails, I need to send the pageToken I got from my previous request with my new request.

Think of it like flipping through a book, where you get to decide how many "words" are on a page (using the maxResults parameter). When you stop getting a pageToken back from Google, you're at the end of the book and have requested all available information.

pageToken only seems to be available on the Gmail Advanced Service.

Ian Hyzy
  • 481
  • 5
  • 26
  • Where is the documentation for pageToken in the Gmail Advanced Service link? Also I can't seem to find an API for the Drive... Gmail... advanced objects? – CodeCamper Nov 21 '19 at 04:50
  • 1
    Check [here](https://developers.google.com/gmail/api/v1/reference/users/messages/list#parameters). – Iamblichus Nov 21 '19 at 09:28
  • Linking the *REST* API with a `string` token isn't very helpful, because the question is about paged API calls to the google App Scripts javascript API which uses a `Number` token. – Carl Walsh Jun 04 '23 at 15:50
2

IMHO the pragmatic interpretation of

Where the thread size is unknown, and potentially very large, please use the 'paged' call, and specify ranges of the threads to retrieve in each call.

is to use search(query, start, max) instead of query(query)

While understanding each technical term might be very helpful, it's more important to interpret them considering the whole statement and context.

Rubén
  • 34,714
  • 9
  • 70
  • 166