Range

Range( set, from, to )
Range( set, from, to )
Range( set, from, to )
Range( set, from, to )
range( set, from, to )
Range( set, from, to )

Description

The Range function returns an inclusive subset of the values from the provided set that includes the range of values starting from from up to to, as defined by the order of the set.

Items in the set can be:

  • single, scalar values

  • tuples containing a variety of values of different types

from and to are expressed as prefixes that need to match some, or all, of the structure provided by the set, or Range returns an empty set. Prefix-based matching means that, if your set contains two or more fields, you only need to specify the first field in from or to to achieve a match. You may have to specify additional fields if there are multiple entries in the set that would match the first field.

For example, if an index’s values field contains last and first fields, from or to can be expressed as just a last name, or an array containing the last and first names to mark a boundary of the range.

When from or to match an entry in the set, that’s where the boundary for the range is set; no further evaluation is done.

Both from and to can be expressed as an empty array, which indicates that the range should extend to, respectively, the set’s first item, or the set’s last item. If both from and to are expressed as an empty arrange, the entire range is returned.

If you use Range on a collection containing many documents, there is a chance that evaluating the range could exceed the transaction time limit of 30 seconds.

Parameters

Argument Type Definition and Requirements

set

Set

The set

from

Value, or Array of values

The value(s) marking the start of the range to return. from is inclusive.

Use an empty array to indicate that from should start with the first item in the set.

to

Value, or Array of values

The value(s) marking the end of the range to return. to is inclusive.

Use an empty array to indicate that to should end with the last item in the set.

Returns

A new set containing values from set in the range between from and to inclusive.

Examples

With a collection containing the letters of the alphabet, and an index with a values field defined to contain each document’s letter field, the following query returns the range of values from F to M:

Value result = await client.Query(
  Paginate(
    Range(Match(Index("letters")), "F", "M")
  )
);
  result, err := client.Query(
    f.Paginate(
      f.Range(
        f.Match(
          f.Index("letters")),
          "F", "M")))
System.out.println(
    client.query(
        Paginate(
            Range(Match(Index("letters")), Value("F"), Value("M"))
        )
    ).get());
client.query(
  q.Paginate(
    q.Range(q.Match(q.Index('letters')), 'F', 'M')
  )
)
.then((ret) => console.log(ret))
print(client.query(
  q.paginate(
    q.range(q.match(q.index("letters")), "F", "M")
  )
))
println(Await.result(
  client.query(
    Paginate(
      Range(Match(Index("letters")), "F", "M")
    )
  ),
  5.seconds
))
{
  "object": {
    "data": [
      "F",
      "G",
      "H",
      "I",
      "J",
      "K",
      "L",
      "M"
    ]
  }
}
map[data:[F G H I J K L M]]
{data: ["F", "G", "H", "I", "J", "K", "L", "M"]}
{ data: [ 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M' ] }
{'data': ['F', 'G', 'H', 'I', 'J', 'K', 'L', 'M']}
{data: ["F", "G", "H", "I", "J", "K", "L", "M"]}

With the same setup, the following query returns all of the letters up to, and including, M:

Value result = await client.Query(
  Paginate(
    Range(Match(Index("letters")), Arr(), "M")
  )
);
  result, err := client.Query(
    f.Paginate(
      f.Range(
        f.Match(
          f.Index("letters")),
          f.Arr{}, "M")))
System.out.println(
    client.query(
        Paginate(
            Range(Match(Index("letters")), Arr(), Value("M"))
        )
    ).get());
client.query(
  q.Paginate(
    q.Range(q.Match(q.Index('letters')), [], 'M')
  )
)
.then((ret) => console.log(ret))
print(client.query(
  q.paginate(
    q.range(q.match(q.index("letters")), [], "M")
  )
))
println(Await.result(
  client.query(
    Paginate(
      Range(Match(Index("letters")), Arr(), "M")
    )
  ),
  5.seconds
))
{
  "object": {
    "data": [
      "A",
      "B",
      "C",
      "D",
      "E",
      "F",
      "G",
      "H",
      "I",
      "J",
      "K",
      "L",
      "M"
    ]
  }
}
map[data:[A B C D E F G H I J K L M]]
{data: ["A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M"]}
{ data:
   [ 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M' ] }
{'data': ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M']}
{data: ["A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M"]}

With the same setup, the following query returns F and all of the subsequent letters:

Value result = await client.Query(
  Paginate(
    Range(Match(Index("letters")), "F", Arr())
  )
);
  result, err := client.Query(
    f.Paginate(
      f.Range(
        f.Match(
          f.Index("letters")),
          "F", f.Arr{})))
System.out.println(
    client.query(
        Paginate(
            Range(Match(Index("letters")), Value("F"), Arr())
        )
    ).get());
client.query(
  q.Paginate(
    q.Range(q.Match(q.Index('letters')), 'F', [])
  )
)
.then((ret) => console.log(ret))
print(client.query(
  q.paginate(
    q.range(q.match(q.index("letters")), "F", [])
  )
))
println(Await.result(
  client.query(
    Paginate(
      Range(Match(Index("letters")), "F", Arr())
    )
  ),
  5.seconds
))
{
  "object": {
    "data": [
      "F",
      "G",
      "H",
      "I",
      "J",
      "K",
      "L",
      "M",
      "N",
      "O",
      "P",
      "Q",
      "R",
      "S",
      "T",
      "U",
      "V",
      "W",
      "X",
      "Y",
      "Z"
    ]
  }
}
map[data:[F G H I J K L M N O P Q R S T U V W X Y Z]]
{data: ["F", "G", "H", "I", "J", "K", "L", "M", "N", "O", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z"]}
{ data:
   [ 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P',
     'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z' ] }
{'data': ['F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O',
 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z']}
{data: ["F", "G", "H", "I", "J", "K", "L", "M", "N", "O", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z"]}

The schema setup is not documented here. Most of what you need to make this example work is included in the Index tutorials, including the creation of the collection and the creation of the letters documents. You would need to create an appropriate index, which should look like this:

{ ref: Index("letters"),
  ts: 1566580712100000,
  active: true,
  serialized: true,
  name: 'letters',
  source: Collection("Letters"),
  values: [ { field: [ 'data', 'letter' ] } ],
  partitions: 8 }

With a collection containing people, with first and last names, and an index with a values field defined to contain the last and first fields, the following query returns all of the people from Hopper to Minsky:

Value result = await client.Query(
  Paginate(
    Range(
      Match(Index("people_by_last_first")), "Hopper", "Minsky"
    )
  )
);
  result, err := client.Query(
    f.Paginate(
      f.Range(
        f.Match(
          f.Index("people_by_last_first")),
          "Hopper", "Minksy")))
    System.out.println(
        client.query(
            Paginate(
                Range(
                    Match(Index("people_by_last_first")),
                    Value("Hopper"), Value("Minsky")
                )
            )
        ).get());
client.query(
  q.Paginate(
    q.Range(
      q.Match(q.Index('people_by_last_first')), 'Hopper', 'Minsky'
    )
  )
)
.then((ret) => console.log(ret))
print(client.query(
  q.paginate(
    q.range(
      q.match(q.index("people_by_last_first")), "Hopper", "Minsky"
    )
  )
))
println(Await.result(
  client.query(
    Paginate(
      Range(Match(Index("people_by_last_first")), "Hopper", "Minsky")
    )
  ),
  5.seconds
))
{
  "object": {
    "data": [
      [
        "Hopper",
        "Grace"
      ],
      [
        "Lamport",
        "Leslie"
      ],
      [
        "Minsky",
        "Marvin"
      ]
    ]
  }
}
ap[data:[[Hopper Grace] [Lamport Leslie]]]
{data: [["Hopper", "Grace"], ["Lamport", "Leslie"], ["Minsky", "Marvin"]]}
{ data:
   [ [ 'Hopper', 'Grace' ],
     [ 'Lamport', 'Leslie' ],
     [ 'Minsky', 'Marvin' ] ] }
{'data': [['Hopper', 'Grace'], ['Lamport', 'Leslie'], ['Minsky', 'Marvin']]}
{data: [["Hopper", "Grace"], ["Lamport", "Leslie"], ["Minsky", "Marvin"]]}

See the Index tutorials for the setup of the People collection. You would need to create an appropriate index, which should look like this:

{ ref: Index("people_by_last_first"),
  ts: 1570226020940000,
  active: true,
  serialized: true,
  name: 'people_by_last_first',
  source: Collection("People"),
  values:
   [ { field: [ 'data', 'last' ] },
     { field: [ 'data', 'first' ] } ],
  partitions: 8 }

With a collection containing people, with age, and first and last names, and an index with a values field defined to contain the age and first fields, the following query returns all of the people from 80, Leslie to 92, Marvin:

Not available in this language yet.
result, err := client.Query(
  f.Paginate(
    f.Range(
      f.Match(
        f.Index("people_by_age_first")),
        f.Arr{80, "Leslie"},
        f.Arr{92, "Marvin"})))
System.out.println(
    client.query(
        Paginate(
            Range(
                Match(Index("people_by_age_first")),
                Arr(Value(80), Value("Leslie")),
                Arr(Value(92), Value("Marvin"))
            )
        )
    ).get()
);
client.query(
  q.Paginate(
    q.Range(
      q.Match(q.Index('people_by_age_first')),
      [80, 'Leslie'],
      [92, 'Marvin'],
    )
  )
)
.then((ret) => console.log(ret))
Not available in this language yet.
println(Await.result(
  client.query(
    Paginate(
        Range(
            Match(Index("people_by_age_first")),
            Arr(80, "Leslie"),
            Arr(92, "Marvin")
        )
    )
  ),
  5.seconds
))
map[data:[[80 Leslie] [81 Stephen] [92 Marvin]]]
{data: [[80, "Leslie"], [81, "Stephen"], [92, "Marvin"]]}
{ data: [ [ 80, 'Leslie' ], [ 81, 'Stephen' ], [ 92, 'Marvin' ] ] }
{data: [[80, "Leslie"], [81, "Stephen"], [92, "Marvin"]]}

If we repeat the query, but only use the person’s age in the range, the same result is returned:

Not available in this language yet.
result, err := client.Query(
  f.Paginate(
    f.Range(
      f.Match(
        f.Index("people_by_age_first")),
        f.Arr{80},
        f.Arr{92})))
System.out.println(
    client.query(
        Paginate(
            Range(
                Match(Index("people_by_age_first")),
                Arr(Value(80)),
                Arr(Value(92))
            )
        )
    ).get()
);
client.query(
  q.Paginate(
    q.Range(
      q.Match(q.Index('people_by_age_first')),
      [80],
      [92],
    )
  )
)
.then((ret) => console.log(ret))
Not available in this language yet.
println(Await.result(
  client.query(
    Paginate(
        Range(
            Match(Index("people_by_age_first")),
            Arr(80),
            Arr(92)
        )
    )
  ),
  5.seconds
))
map[data:[[80 Leslie] [81 Stephen] [92 Marvin]]]
{data: [[80, "Leslie"], [81, "Stephen"], [92, "Marvin"]]}
{ data: [ [ 80, 'Leslie' ], [ 81, 'Stephen' ], [ 92, 'Marvin' ] ] }
{data: [[80, "Leslie"], [81, "Stephen"], [92, "Marvin"]]}

Was this article helpful?

We're sorry to hear that.
Tell us how we can improve!
Visit Fauna's Discourse forums or email docs@fauna.com

Thank you for your feedback!