Sort and Filter

Several of the Files.com API resources have list operations that return multiple instances of the resource. The List operations can be sorted and filtered.

Sorting

To sort the returned data, pass in the SortBy method argument.

Each resource supports a unique set of valid sort fields and can only be sorted by one field at a time.

The argument value is a Go map[string]interface{} map that has a key of the resource field name to sort on and a value of either "asc" or "desc" to specify the sort order.

Special note about the List Folder Endpoint

For historical reasons, and to maintain compatibility with a variety of other cloud-based MFT and EFSS services, Folders will always be listed before Files when listing a Folder. This applies regardless of the sorting parameters you provide. These will be used, after the initial sort application of Folders before Files.

Sort Example

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    "github.com/Files-com/files-sdk-go/v3/user"
)

client := user.Client{Config: files_sdk.GlobalConfig}

// users sorted by username
parameters := files_sdk.UserListParams{SortBy: map[string]interface{}{"username":"asc"}}
userIterator, err := client.List(parameters)
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

for userIterator.Next() {
  user := userIterator.User()
  fmt.Println(user.Username)
}
err = userIterator.Err()
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

Filtering

Filters apply selection criteria to the underlying query that returns the results. They can be applied individually or combined with other filters, and the resulting data can be sorted by a single field.

Each resource supports a unique set of valid filter fields, filter combinations, and combinations of filters and sort fields.

The passed in argument is a Go map[string]interface{} map that has a key of the resource field name to filter on and a passed in value to use in the filter comparison.

Filter Types

Filter	Type	Description
`Filter`	Exact	Find resources that have an exact field value match to a passed in value. (i.e., FIELD_VALUE = PASS_IN_VALUE).
`FilterPrefix`	Pattern	Find resources where the specified field is prefixed by the supplied value. This is applicable to values that are strings.
`FilterGt`	Range	Find resources that have a field value that is greater than the passed in value. (i.e., FIELD_VALUE > PASS_IN_VALUE).
`FilterGteq`	Range	Find resources that have a field value that is greater than or equal to the passed in value. (i.e., FIELD_VALUE >= PASS_IN_VALUE).
`FilterLt`	Range	Find resources that have a field value that is less than the passed in value. (i.e., FIELD_VALUE < PASS_IN_VALUE).
`FilterLteq`	Range	Find resources that have a field value that is less than or equal to the passed in value. (i.e., FIELD_VALUE <= PASS_IN_VALUE).

Exact Filter Example

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    "github.com/Files-com/files-sdk-go/v3/user"
)

client := user.Client{Config: files_sdk.GlobalConfig}

// non admin users
parameters := files_sdk.UserListParams{
    Filter: map[string]interface{}{"not_site_admin": true}
}
userIterator, err := client.List(parameters)
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

for userIterator.Next() {
  user := userIterator.User()
  fmt.Println(user.Username)
}
err = userIterator.Err()
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

Range Filter Example

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    "github.com/Files-com/files-sdk-go/v3/user"
)

client := user.Client{Config: files_sdk.GlobalConfig};

// users who haven't logged in since 2024-01-01
parameters := files_sdk.UserListParams{
    FilterLt: map[string]interface{}{"last_login_at": "2024-01-01"}
}
userIterator, err := client.List(parameters)
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

for userIterator.Next() {
  user := userIterator.User()
  fmt.Println(user.Username)
}
err = userIterator.Err()
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

Pattern Filter Example

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    "github.com/Files-com/files-sdk-go/v3/user"
)

client := user.Client{Config: files_sdk.GlobalConfig};

// users whose usernames start with 'test'
parameters := files_sdk.UserListParams{
    FilterPrefix: map[string]interface{}{"username": "test"}
}
userIterator, err := client.List(parameters)
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

for userIterator.Next() {
  user := userIterator.User()
  fmt.Println(user.Username)
}
err = userIterator.Err()
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

Combination Filter with Sort Example

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    "github.com/Files-com/files-sdk-go/v3/user"
)

client := user.Client{Config: files_sdk.GlobalConfig};

// users whose usernames start with 'test' and are not admins
parameters := files_sdk.UserListParams{
    FilterPrefix: map[string]interface{}{"username": "test"},
    Filter:       map[string]interface{}{"not_site_admin": true},
    SortBy:       map[string]interface{}{"username": "asc"}
}
userIterator, err := client.List(parameters)
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

for userIterator.Next() {
  user := userIterator.User()
  fmt.Println(user.Username)
}
err = userIterator.Err()
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}