How to precisely control the number of documents returned and the starting offset of AnQiCMS document list (advanced usage of `limit` parameter)?

When building and managing website content, AnQiCMS provides a series of flexible API interfaces to help us accurately obtain and display data. Among them,archive/listThe interface is the core to obtain the document list, and itslimitparameters, in terms of controlling the number of returned items and the starting offset, demonstrate its powerful fine-grained control ability. Understand and make good use oflimitAdvanced usage of the parameter, which can make our website content display more flexible and efficient.

limitBasic usage of the parameter: control the number of returned items.

limitThe most direct use of the parameter is to specify how many records you want to retrieve from the document list. For example, when you want to display the latest 5 articles in a certain block of a website, or 10 popular recommendations in a certain category,limitParameters can be put to good use.

You can use it like this:

/api/archive/list?moduleId=1&limit=5

This request will return the article model (moduleId=1) the latest 5 articles. In this mode,limitfollowed by a number, AnQiCMS will get the query results frombeginningStart, return the specified number of documents. This is very practical in many scenarios that require displaying a fixed amount of content, such as "Latest News", "Great Reviews", etc.

limitAdvanced usage of parameters: precise control of the starting offset and return quantity

limitThe real strength of the parameter lies in the advanced usage it provides, allowing us to not only control the number of returns but also to specify exactly from which record to start. When you need to skip the first few records, or not use the traditional pagination mode (type="page"In the case of, when extracting a part of the data from the middle of the result set, this usage is particularly important.

Advanced usage by passing two values separated by a comma string:limit="OFFSET,COUNT".

• OFFSET (offset amount): This is the number of records you want to skip. Please note that it representshow many records to skip rather than starting from which record. For example,OFFSET=0Starting from the first record,OFFSET=2Then it means skipping the first two records, starting from the third to retrieve.
• COUNT (quantity): This is the number of records you want to return.

Let's look at a specific example:

/api/archive/list?moduleId=1&limit=2,5&order=created_time desc

The meaning of this request is: from the article model (moduleId=1In this case, skip the first 2 records (sorted in descending order by publish time), and then return the next 5 records starting from the 3rd record.

This flexible control method brings great convenience to content display:

• Skip specific contentIf your website has featured articles or recommended content, you may want to skip these entries that have already been specially displayed in the regular list. By setting an appropriateOFFSETValue, you can easily achieve this. For example, if the top of the homepage has already displayed 1 headline article, and you want other areas to display the remaining latest articles, you can uselimit=1,N(N is the number of remaining articles you want to get).
• Build a complex layoutIn complex page layouts, it may be necessary to display different parts of the same document list in different locations.For example, a page is divided into a left-hand hot recommendation and a right-hand ordinary list. The hot recommendations take the first 3, and the right-hand ordinary list takes the 4th to the 10th.limit='0,3'andlimit='3,7'(This means taking 3 articles starting from the first and 7 articles starting from the fourth), which can be very elegantly implemented.

limitwithtypeparameter collaboration

Inarchive/listin the interface,limitthe behavior of the parameter will also be affected bytypethe parameter's influence. By default,typehas a value oflistIn this case,limit="OFFSET,COUNT"the pattern can be used directly.

However, when we settype="page"enable traditional pagination mode,limitthe parameter will be the number of items displayed per page, andpageThe parameter is used to control the page number (i.e., it implicitly controls the offset). In this case, you do not need to useOFFSET,COUNTthe format, butlimitspecify the number of items per page separately,pageand specify the current page number.

For example, if you need to get the second page of the article list, with 10 items per page, your request would be:

/api/archive/list?moduleId=1&type=page&page=2&limit=10&order=created_time desc

Please pay close attention to this distinction:limit="OFFSET,COUNT"Primarily used fortype="list"ortype="related"In scenarios where pagination does not apply, or when you need to highly customize the starting position and quantity rather than in the traditional sense of 'pages'.

To ensure that each request results in a stable and consistent outcome, especially when usingOFFSET,COUNTpatterns, it is strongly recommended to use parameters to explicitly specify the sorting method, for exampleorderfor exampleorder='created_time desc'Otherwise, in cases of large data volume or frequent updates, the default sorting may cause the 'Nth record' you obtain to not always be the one you expect.

Summary

AnQiCMS'limitThe parameter is not just a simple quantity controller, through itsOFFSET,COUNTAdvanced usage, it has become a powerful data extraction tool.In order to achieve specific content display logic, optimize page loading, or build a more refined website content layout, mastering this method will greatly enhance your efficiency and flexibility in AnQiCMS content operation and development.

Frequently Asked Questions (FAQ)

Q1:limit='5'andlimit='0,5'What is the difference?A1: In terms of function,limit='5'andlimit='0,5'The effect is completely the same. They all indicate starting from the first record in the result set (i.e., skipping 0 records) and returning the next 5 records.limit='5'It is a shorthand form, which can be used when you only need to specify the number of returns without explicitly specifying the offset, making it a more concise expression.

Q2: When usinglimit='OFFSET,COUNT'If myOFFSETWhat will happen if the value is too large and exceeds the total number of documents?A2: If you specifyOFFSETThe value is greater than or equal to the total number of documents under the current query condition, the API will return an empty document list (dataThe field is an empty array), at the same timecodeIt remains 0, indicating that the request was successful but no documents meeting the criteria were found.

Q3:limitCan the parameter be used with other filtering conditions (such ascategoryId/flag)?A3: Of course, you can.limitThe parameter takes effect after all other filtering and sorting conditions are processed. This means that AnQiCMS will first sort according tomoduleId/categoryId/flag/qand then filter out the document set that meets the conditions according toorderThe parameter sorts these documents and then based onlimitthe parameter to return the documents with specified quantity and offset.