cosmos-sdk: github.com/cosmos/cosmos-sdk/types/query Index | Examples | Files

package query

import "github.com/cosmos/cosmos-sdk/types/query"

Index

Examples

Package Files

filtered_pagination.go pagination.go pagination.pb.go

Variables

var (
    ErrInvalidLengthPagination        = fmt.Errorf("proto: negative length found during unmarshaling")
    ErrIntOverflowPagination          = fmt.Errorf("proto: integer overflow")
    ErrUnexpectedEndOfGroupPagination = fmt.Errorf("proto: unexpected end of group")
)

type PageRequest Uses

type PageRequest struct {
    // key is a value returned in PageResponse.next_key to begin
    // querying the next page most efficiently. Only one of offset or key
    // should be set.
    Key []byte `protobuf:"bytes,1,opt,name=key,proto3" json:"key,omitempty"`
    // offset is a numeric offset that can be used when key is unavailable.
    // It is less efficient than using key. Only one of offset or key should
    // be set.
    Offset uint64 `protobuf:"varint,2,opt,name=offset,proto3" json:"offset,omitempty"`
    // limit is the total number of results to be returned in the result page.
    // If left empty it will default to a value to be set by each app.
    Limit uint64 `protobuf:"varint,3,opt,name=limit,proto3" json:"limit,omitempty"`
    // count_total is set to true  to indicate that the result set should include
    // a count of the total number of items available for pagination in UIs. count_total
    // is only respected when offset is used. It is ignored when key is set.
    CountTotal bool `protobuf:"varint,4,opt,name=count_total,json=countTotal,proto3" json:"count_total,omitempty"`
}

PageRequest is to be embedded in gRPC request messages for efficient pagination. Ex:

message SomeRequest {
        Foo some_parameter = 1;
        PageRequest pagination = 2;
}

func (*PageRequest) Descriptor Uses

func (*PageRequest) Descriptor() ([]byte, []int)

func (*PageRequest) GetCountTotal Uses

func (m *PageRequest) GetCountTotal() bool

func (*PageRequest) GetKey Uses

func (m *PageRequest) GetKey() []byte

func (*PageRequest) GetLimit Uses

func (m *PageRequest) GetLimit() uint64

func (*PageRequest) GetOffset Uses

func (m *PageRequest) GetOffset() uint64

func (*PageRequest) Marshal Uses

func (m *PageRequest) Marshal() (dAtA []byte, err error)

func (*PageRequest) MarshalTo Uses

func (m *PageRequest) MarshalTo(dAtA []byte) (int, error)

func (*PageRequest) MarshalToSizedBuffer Uses

func (m *PageRequest) MarshalToSizedBuffer(dAtA []byte) (int, error)

func (*PageRequest) ProtoMessage Uses

func (*PageRequest) ProtoMessage()

func (*PageRequest) Reset Uses

func (m *PageRequest) Reset()

func (*PageRequest) Size Uses

func (m *PageRequest) Size() (n int)

func (*PageRequest) String Uses

func (m *PageRequest) String() string

func (*PageRequest) Unmarshal Uses

func (m *PageRequest) Unmarshal(dAtA []byte) error

func (*PageRequest) XXX_DiscardUnknown Uses

func (m *PageRequest) XXX_DiscardUnknown()

func (*PageRequest) XXX_Marshal Uses

func (m *PageRequest) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*PageRequest) XXX_Merge Uses

func (m *PageRequest) XXX_Merge(src proto.Message)

func (*PageRequest) XXX_Size Uses

func (m *PageRequest) XXX_Size() int

func (*PageRequest) XXX_Unmarshal Uses

func (m *PageRequest) XXX_Unmarshal(b []byte) error

type PageResponse Uses

type PageResponse struct {
    // next_key is the key to be passed to PageRequest.key to
    // query the next page most efficiently
    NextKey []byte `protobuf:"bytes,1,opt,name=next_key,json=nextKey,proto3" json:"next_key,omitempty"`
    // total is total number of results available if PageRequest.count_total
    // was set, its value is undefined otherwise
    Total uint64 `protobuf:"varint,2,opt,name=total,proto3" json:"total,omitempty"`
}

PageResponse is to be embedded in gRPC response messages where the corresponding request message has used PageRequest

message SomeResponse {
        repeated Bar results = 1;
        PageResponse page = 2;
}

func FilteredPaginate Uses

func FilteredPaginate(
    prefixStore types.KVStore,
    pageRequest *PageRequest,
    onResult func(key []byte, value []byte, accumulate bool) (bool, error),
) (*PageResponse, error)

FilteredPaginate does pagination of all the results in the PrefixStore based on the provided PageRequest. onResult should be used to do actual unmarshaling and filter the results. If key is provided, the pagination uses the optimized querying. If offset is used, the pagination uses lazy filtering i.e., searches through all the records. The accumulate parameter represents if the response is valid based on the offset given. It will be false for the results (filtered) < offset and true for `offset > accumulate <= end`. When accumulate is set to true the current result should be appended to the result set returned to the client.

Code:

app, ctx, appCodec := setupTest()

var balances sdk.Coins
for i := 0; i < numBalances; i++ {
    denom := fmt.Sprintf("foo%ddenom", i)
    balances = append(balances, sdk.NewInt64Coin(denom, 100))
}

for i := 0; i < 5; i++ {
    denom := fmt.Sprintf("test%ddenom", i)
    balances = append(balances, sdk.NewInt64Coin(denom, 250))
}
addr1 := sdk.AccAddress([]byte("addr1"))
acc1 := app.AccountKeeper.NewAccountWithAddress(ctx, addr1)
app.AccountKeeper.SetAccount(ctx, acc1)
err := app.BankKeeper.SetBalances(ctx, addr1, balances)
if err != nil { // should return no error
    fmt.Println(err)
}

pageReq := &query.PageRequest{Key: nil, Limit: 1, CountTotal: true}
store := ctx.KVStore(app.GetKey(authtypes.StoreKey))
balancesStore := prefix.NewStore(store, types.BalancesPrefix)
accountStore := prefix.NewStore(balancesStore, addr1.Bytes())

var balResult sdk.Coins
pageRes, err := query.FilteredPaginate(accountStore, pageReq, func(key []byte, value []byte, accumulate bool) (bool, error) {
    var bal sdk.Coin
    err := appCodec.UnmarshalBinaryBare(value, &bal)
    if err != nil {
        return false, err
    }

    // filter balances with amount greater than 100
    if bal.Amount.Int64() > int64(100) {
        if accumulate {
            balResult = append(balResult, bal)
        }

        return true, nil
    }

    return false, nil
})

if err != nil { // should return no error
    fmt.Println(err)
}
fmt.Println(&types.QueryAllBalancesResponse{Balances: balResult, Pagination: pageRes})

Output:

balances:<denom:"test0denom" amount:"250" > pagination:<next_key:"test1denom" total:5 >

func Paginate Uses

func Paginate(
    prefixStore types.KVStore,
    pageRequest *PageRequest,
    onResult func(key []byte, value []byte) error,
) (*PageResponse, error)

Paginate does pagination of all the results in the PrefixStore based on the provided PageRequest. onResult should be used to do actual unmarshaling.

Code:

app, ctx, _ := setupTest()

var balances sdk.Coins

for i := 0; i < 2; i++ {
    denom := fmt.Sprintf("foo%ddenom", i)
    balances = append(balances, sdk.NewInt64Coin(denom, 100))
}

addr1 := sdk.AccAddress([]byte("addr1"))
acc1 := app.AccountKeeper.NewAccountWithAddress(ctx, addr1)
app.AccountKeeper.SetAccount(ctx, acc1)
err := app.BankKeeper.SetBalances(ctx, addr1, balances)
if err != nil {
    fmt.Println(err)
}
// Paginate example
pageReq := &query.PageRequest{Key: nil, Limit: 1, CountTotal: true}
request := types.NewQueryAllBalancesRequest(addr1, pageReq)
balResult := sdk.NewCoins()
authStore := ctx.KVStore(app.GetKey(authtypes.StoreKey))
balancesStore := prefix.NewStore(authStore, types.BalancesPrefix)
accountStore := prefix.NewStore(balancesStore, addr1.Bytes())
pageRes, err := query.Paginate(accountStore, request.Pagination, func(key []byte, value []byte) error {
    var tempRes sdk.Coin
    err := app.Codec().UnmarshalBinaryBare(value, &tempRes)
    if err != nil {
        return err
    }
    balResult = append(balResult, tempRes)
    return nil
})
if err != nil { // should return no error
    fmt.Println(err)
}
fmt.Println(&types.QueryAllBalancesResponse{Balances: balResult, Pagination: pageRes})

Output:

balances:<denom:"foo0denom" amount:"100" > pagination:<next_key:"foo1denom" total:2 >

func (*PageResponse) Descriptor Uses

func (*PageResponse) Descriptor() ([]byte, []int)

func (*PageResponse) GetNextKey Uses

func (m *PageResponse) GetNextKey() []byte

func (*PageResponse) GetTotal Uses

func (m *PageResponse) GetTotal() uint64

func (*PageResponse) Marshal Uses

func (m *PageResponse) Marshal() (dAtA []byte, err error)

func (*PageResponse) MarshalTo Uses

func (m *PageResponse) MarshalTo(dAtA []byte) (int, error)

func (*PageResponse) MarshalToSizedBuffer Uses

func (m *PageResponse) MarshalToSizedBuffer(dAtA []byte) (int, error)

func (*PageResponse) ProtoMessage Uses

func (*PageResponse) ProtoMessage()

func (*PageResponse) Reset Uses

func (m *PageResponse) Reset()

func (*PageResponse) Size Uses

func (m *PageResponse) Size() (n int)

func (*PageResponse) String Uses

func (m *PageResponse) String() string

func (*PageResponse) Unmarshal Uses

func (m *PageResponse) Unmarshal(dAtA []byte) error

func (*PageResponse) XXX_DiscardUnknown Uses

func (m *PageResponse) XXX_DiscardUnknown()

func (*PageResponse) XXX_Marshal Uses

func (m *PageResponse) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*PageResponse) XXX_Merge Uses

func (m *PageResponse) XXX_Merge(src proto.Message)

func (*PageResponse) XXX_Size Uses

func (m *PageResponse) XXX_Size() int

func (*PageResponse) XXX_Unmarshal Uses

func (m *PageResponse) XXX_Unmarshal(b []byte) error

Package query imports 6 packages (graph) and is imported by 18 packages. Updated 2020-07-26. Refresh now. Tools for package owners.