Query methods — PyGreSQL 5.0 documentation

# Query methods

class `pg.` `Query`

The `Query` object returned by `Connection.query()` and `DB.query()` provides the following methods for accessing the results of the query:

## getresult – get query values as list of tuples

`Query.` `getresult`()

  Get query values as list of tuples

  Returns: | result values as a list of tuples
  Return type: | list
  Raises: | TypeError – too many (any) parameters MemoryError – internal memory error

This method returns the list of the values returned by the query. More information about this result may be accessed using `Query.listfields()`, `Query.fieldname()` and `Query.fieldnum()` methods.

Note that since PyGreSQL 5.0 this will return the values of array type columns as Python lists.

## dictresult – get query values as list of dictionaries

`Query.` `dictresult`()

  Get query values as list of dictionaries

  Returns: | result values as a list of dictionaries
  Return type: | list
  Raises: | TypeError – too many (any) parameters MemoryError – internal memory error

This method returns the list of the values returned by the query with each tuple returned as a dictionary with the field names used as the dictionary index.

Note that since PyGreSQL 5.0 this will return the values of array type columns as Python lists.

## namedresult – get query values as list of named tuples

`Query.` `namedresult`()

  Get query values as list of named tuples

  Returns: | result values as a list of named tuples
  Return type: | list
  Raises: | TypeError – too many (any) parameters TypeError – named tuples not supported MemoryError – internal memory error

This method returns the list of the values returned by the query with each row returned as a named tuple with proper field names.

Column names in the database that are not valid as field names for named tuples (particularly, names starting with an underscore) are automatically renamed to valid positional names.

Note that since PyGreSQL 5.0 this will return the values of array type columns as Python lists.

New in version 4.1.

## listfields – list fields names of previous query result

`Query.` `listfields`()

  List fields names of previous query result

  Returns: | field names
  Return type: | list
  Raises: | TypeError – too many parameters

This method returns the list of names of the fields defined for the query result. The fields are in the same order as the result values.

## fieldname, fieldnum – field name/number conversion

`Query.` `fieldname`(num)

  Get field name from its number

  Parameters: | num (int) – field number
  Returns: | field name
  Return type: | str
  Raises: | TypeError – invalid connection, bad parameter type, or too many parameters ValueError – invalid field number

This method allows to find a field name from its rank number. It can be useful for displaying a result. The fields are in the same order as the result values.

`Query.` `fieldnum`(name)

  Get field number from its name

  Parameters: | name (str) – field name
  Returns: | field number
  Return type: | int
  Raises: | TypeError – invalid connection, bad parameter type, or too many parameters ValueError – unknown field name

This method returns a field number from its name. It can be used to build a function that converts result list strings to their correct type, using a hardcoded table definition. The number returned is the field rank in the result values list.

## ntuples – return number of tuples in query object

`Query.` `ntuples`()

  Return number of tuples in query object

  Returns: | number of tuples in `Query`
  Return type: | int
  Raises: | TypeError – Too many arguments.

This method returns the number of tuples found in a query.