---
name: "Tangram::Cursor"
section: "3pm"
platform: "linux"
package: "libtangram-perl"
version: "2.12-4"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Tangram::Cursor"
---

# Tangram::Cursor(3pm)

traverse a result set

## NAME

Tangram::Cursor - traverse a result set

## SYNOPSIS

```
   $cursor = $storage->cursor($remote, $filter);
   while (my $obj = $cursor->current())
   {
      # process $obj
      $cursor->next();
   }
   $cursor->execute();
   while (my $obj = $cursor->current())
   {
      # process $obj
      $cursor->next();
   }
```

## DESCRIPTION

A Cursor makes it possible to iterate over a result set without loading all the objects in memory.

See also the "limit" option to the select method of the Tangram::Storage class.

## INSTANCE METHODS

### current

```
   $obj = $cursor->current();
```

Returns the current object, or **undef()** if the result set is exhausted.

### next

```
   $obj = $cursor->next();
   @obj = $cursor->next();
```

Moves to the next object in the result set, if any. Returns the new current object, or **undef()** if the result set is exhausted. In list context, return all the remaining objects.

### execute

```
   $cursor->execute();
```

Moves the cursor to the first object in the result set, and return it. Note that preparing Cursors is an expensive operation, you should reuse them if possible. **execute()** allows just that.

**execute()** may be called several times in a row, or on a Cursor that has just been obtained from a Storage, without ill effects.

### residue

```
   my @vals = $cursor->residue();
```

Returns the values of the Expr that were passed to the `"retrieve"` directive of the **Storage::select()** or **Storage::cursor()** statement.

## CURSORS AND CONNECTIONS

Each Cursor opens its own connection to the database.

## SEE ALSO

Tangram::Storage