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 for fetching document lists, and itlimitThe parameters, in terms of controlling the number of returned items and the starting offset, demonstrate its powerful fine-grained control ability. Understanding and utilizinglimitAdvanced usage of parameters, allowing our website content display to be more flexible and efficient.

limitBasic usage of parameters: 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 block of a website or 10 popular recommendations under 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 under. In this mode,limitfollowed by a number, AnQiCMS will retrieve the articles from the search resultsfrom the beginningStart, return the specified number of documents. This is very practical in many scenarios that require displaying a fixed amount of content, such as 'Latest Updates', 'Featured Reviews', etc.

limitAdvanced usage of parameters: precise control of the starting offset and the number of returned items

limitThe real strength of the parameter lies in its advanced usage, allowing us not only to control the number of returns but also to precisely specify 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，it is particularly important to extract a portion of the data from the middle of the result set.

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

  • OFFSET (Offset)This is the number of records you want to skip. Please note that it representsHow many records to skip, not the starting record. For example,OFFSET=0This indicates starting from the first record,OFFSET=2which means skipping the first two records and starting from the third.
  • COUNT (quantity): This is the number of records you wish 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 modelmoduleId=1In the list, skip the first 2 records (sorted in descending order by publication 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 showcased in a special manner. By setting an appropriateOFFSETYou can easily achieve this. For example, if one headline article has already been displayed at the top of the homepage, and you want to show the remaining latest articles in other areas, you can uselimit=1,N[en] (N is the number of remaining articles you want to retrieve).
  • Build complex layoutsIn some complex page layouts, it may be necessary to display different parts of the same document list at different locations.For example, a page is divided into the left popular recommendations and the right normal list, where the popular recommendations take the first 3, and the right normal list takes the 4th to the 10th.limit='0,3'andlimit='3,7'[en] (This means to take 3 from the first and 7 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,typeThe value oflistat this time,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, insteadlimitspecify 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 special attention to this distinction:limit="OFFSET,COUNT"Mainly applied totype="list"ortype="related"In scenarios where pagination is not needed, or when you need to highly customize the starting position and quantity instead of the traditional 'page' concept.

To ensure that each request yields a stable and consistent result, especially when usingOFFSET,COUNTit is strongly recommended to use it simultaneously withorderparameters to explicitly specify the sorting method, for exampleorder='created_time desc'Otherwise, under conditions of large data volume or frequent updates, the default sorting may not always lead to the "Nth record" you expect to receive.

Summary

AnQiCMSlimitParameters are not just a simple quantity controller, through itsOFFSET,COUNT

Common Questions (FAQ)

Q1:limit='5'andlimit='0,5'What is the difference?A1: Functionally,limit='5'andlimit='0,5'The effect is completely the same. They both 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 an explicit offset.

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 conditions, the API will return an empty document list (dataThe field is an empty array), andcodeStill 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 as)categoryId/flag)?A3: Of course.limitThe parameter takes effect after all other filtering and sorting conditions have been processed. This means that AnQiCMS will first sort according tomoduleId/categoryId/flag/qfilter out the document sets that meet the conditions, then according toorderParameters sort these documents, then according tolimitparameters to return the specified number and offset of documents.