0

I have noticed this on all sorted routes.

The min/max say that they are context sensitive to the sort type yet are documented as date.

How is a date min/max valid when sorting by, for instance votes?

Kevin Montrose
  • 18,660
  • 6
  • 34
  • 62
Sky Sanders
  • 12,068
  • 3
  • 31
  • 60

1 Answers1

1

todate and fromdate always refer to creation date.

min and max are with respect to the current sort. So, where sort=votes they place upper and lower bounds on the score of returned answers/questions.

They can overlap, but do not always do so.

Documentation has been updated to reflect that min and max can be of any number of types.

/search for example.

We try and do "what's expected" given a sort value.

sort can be of some set of values depending (and documented on) the route in question. Common values are creation, activity, name, and the like.

Generally, the value of sort corresponds to a field in the returned objects to sort by:

  • creation -> creation_date
  • name -> display_name
  • activity -> last_activity_date
  • and so on...

In rare cases the sorted field is something that is not exposed by the API - generally as a consequence of being hidden on the site, or only shown to logged in user - such as added on users/{id}/favorites.

added sorts returned questions by the date the user in question "favorited" them. As we don't display such information anywhere on the site, its not returned by the API.

While the possible types of min and max is (now) documented, the range can be inferred based on context. Namely, if the field being sorted has a certain range (votes for instance being positive and negative integers, creation_date being >= Jan 1 1970, etc.) then min and max must fall in the same range.

hot, week, and month sorts are strange beasts. The ordering of the returned results is dependent on the "hotness" - an intentionally undocumented algorithm, subject to change, which drives the front page of the sites - of a set of questions. min and max on these sorts restricts questions by last_activity_date. This is something of a compromise. The API can't really take in "hotness" values, since we can't/won't document them, but it we do acknowledge that they are in some way influenced by last_activity_date; so we let you pass those in for a range.

Kevin Montrose
  • 18,660
  • 6
  • 34
  • 62
  • Ok, that answers the initial question, which I obviated in the edit. As you say, and as I note, min/max are in respect to sort. If the sort is 'votes', how is a date value for min/max valid? min/max should be specified as string with clarification in the summary. – Sky Sanders Jun 12 '10 at 19:23
  • @code poet - I'm aware of the doc oversight. – Kevin Montrose Jun 13 '10 at 04:39
  • Good. Should I spend time coding around it or just wait for the fix? – Sky Sanders Jun 13 '10 at 10:54
  • @code poet - there are more pressing matters at hand, so it depends how long you're willing to wait. It'll probably be at least a few days. – Kevin Montrose Jun 13 '10 at 11:04
  • No problem. just needed a ballpark. I will compensate for now. – Sky Sanders Jun 13 '10 at 11:49
  • 2
    ummmm... it does not affect me but the incorrectly documented min/max are still confusing people and developers. They should be documented as string and context explained in description – Sky Sanders Jun 27 '10 at 17:32
  • @code poet - this is still scheduled to be fixed, don't worry. Other matters are somewhat more pressing. – Kevin Montrose Jun 27 '10 at 17:56
  • i aint worried, my code is covered. but the top rated library on 'apps' is still calling for int? min/max params - how are other developers going to discover this information. just sayin. – Sky Sanders Jun 27 '10 at 18:01
  • kevin, please take a moment or two and edit this question, http://stackapps.com/questions/922, so that we developers can make some progress on this front. – Sky Sanders Jun 28 '10 at 18:29
  • are there plans to explain the usage of each sort type? – Sky Sanders Jul 09 '10 at 00:55
  • @code poet - they can be inferred pretty easily I think, but I added some additional explanation to the answer. – Kevin Montrose Jul 09 '10 at 01:23
  • Yes, inference is possible. Easy is a relative term and relying on inference when a brief explanation is possible is not, in my opinion, the best way to publish an API for public consumption. API specification of an API should specify usage, explicitly, to remove guesswork (inference). You have explained the easily inferred sorts, and i appreciate that, but have omitted the less than obvious 'hot', 'month', 'week' etc. Do we need to bracket the target? If sort is 'week' what day is the start of the week? Or are they all the same, simply returning results from the min/max range? – Sky Sanders Jul 09 '10 at 01:35
  • And if they are all the same, e.g. return high activity for a min/max range, what is the purpose of having multiple values? See, I am pretty good at inference but this has been unclear to me from day one, resulting in multiple attempts at getting information. Seems we are making progress. – Sky Sanders Jul 09 '10 at 01:37
  • @code poet - week, hot, and month correspond to the front page sorts. Those aren't documented explicitly because they are subject to change should the front page behavior change. Think of them as "windows" onto the site. The sort is not guaranteed to be stable in those cases though, so its not quite 1 -> 1. Technically the sort isn't stable on the front page either, but due to caching and session magic you get the appearance that they are. – Kevin Montrose Jul 09 '10 at 01:42
  • But you still have not answered the question of how to apply the min/max date params to these sort types. if the behaviour is indeterminant and indescribable what is the purpose of publishing them ? You see, we client library developers do not like to present partial solutions. It leaves a bad taste in the mouth and keeps us up at night. – Sky Sanders Jul 09 '10 at 01:54
  • @code poet - ah, I see the confusion now. My bad. Yes, hot and its derivative sorts (month, and week) use min & max as limits on last_activity_date. I'll update my answer, along with a bit of rational. – Kevin Montrose Jul 09 '10 at 02:08
  • I see that you are making an effort and I appreciate it but you are still not telling us how to use min/max dates with 'hot', 'week' and 'month'. It seems to me that you are having a hard time looking at the problem from our perspective. Sure, I get it that min/max somehow loosely equate to last_activity, if there was no activity it would not have been 'hot' for the last few days or 'week' or 'month'. What we need to know is how the values we pass in affect the results in relation to the sort. say we sort on 'hot' and pass no min/max - do we get the last couple days 'hot'? 'week', 'month'? – Sky Sanders Jul 09 '10 at 04:59
  • If we want to get what was hot last week, do we pass in a min/max range encompassing the week? what if I sort on week and pass in a range of 4 days? do I get those 4 days back? Do I get a week? If I get a week, what determined the weeek. Why not simply have a single 'hot' sort and use min/max as the range that your algo uses to determine the results. What is the purpose of having fixed value sorts like 2 days, 1 week and 1 month if the values returned are determined by the min/max range - you see, it is not easily inferred. We need you to look at this from a consumer viewpoint and provide info – Sky Sanders Jul 09 '10 at 05:03
  • @code poet - Maybe it will help to think this way... hot, week, and month return the questions on those tabs of the site. For those sorts, min and max filter out questions that have not had any activity (as defined by last_activity_date) in their range. min and max don't behave any differently on the "front page sorts" than they do elsewhere, they still just filter on a single field (conceptually anyway, there's a lot of optimization around front page things that makes the code more complicated than you might suspect). – Kevin Montrose Jul 09 '10 at 05:09
  • This is what I am getting: 'hot', 'week' and 'month' return results similar to those found on the site and are pinned relative to now. The min/max may further limit those results, if set properly, in a way that is ephemeral and will not be further codified. In no case may you specify an arbitrary time period, say last week's 'hot' questions. yes? – Sky Sanders Jul 09 '10 at 06:19
  • @code poet - as I've said, min and max filter based on the last_activity_date. How is that ephemeral? And no, if a question is not considered "hot" (as in, appears on the hot, week, or month tab) in the present there is no way to get its "older hot" status; that information is not present in the API. The only thing here that is not documented is the "hotness formula," which determines where a question appears on the relevant tab (and thus the equivalent sort). – Kevin Montrose Jul 09 '10 at 06:26
  • ok, forget the ephemeral adjective. let me give you a concrete example. A 'month' query with a min/max specifying the last 2 days would return only those records from the 'month' tab that have had activity in the last 2 days. roughly. A min/max that is outside the range implied by the sort would be considered invalid. yes? I am just trying to get a definition that can easily be conveyed to and digested by an average dev, not trying to bust your balls. – Sky Sanders Jul 09 '10 at 06:52
  • @code poet - there's no roughly. Set sort to month and [min, max] to "the last two days" and you get all the questions that appear on the month tab and also have a last_activity_date in the last two days. min and max can be any valid date (>= unix epoch, that is to say), and there is no statement is made about what last_activity_dates may appear on questions returned by a a simple sort=month (ie. no min or max) query. – Kevin Montrose Jul 09 '10 at 07:17
  • ok. good enough for gubment work. – Sky Sanders Jul 09 '10 at 16:51