Comparative Filtering

In addition to address and collection-based filtering, further filtering can be done using a direct equal comparison of values, values that fit in a specified range or even a direct text search.

Filter Types

Equal

The name property is used to target the correct item to filter. The equal filter must take a string property as the value, even if the targeted property is a number.

"eqFilters":[{
    "name":"attributes.Fur Colour",
    "value":"Freedom"
}]

Range

The name property is used to target the correct item to filter. The range filter will take an array of up to two numbers, with the first number being the minimum value and the second number being the maximum value with both numbers being included.

"rangeFilters":[{
    "name":"attributes.age",
    "value":[
        3,
        10
    ]
}]

Search

The search filter simply takes a string value to search across all the properties and attributes in the metadata.

"search": "Freedom"

Filter Targeting

In the above examples you may have noticed the use of the . to target specific items. Since we separate properties and attributes (commonly known as traits in NFT metadata) we need to target them specifically in our filters.

By traits (aliased as attributes)

Filter through the attributes

e.g. attributes.Fur Colour, attributes.Age

By properties

Filter through properties on the metadata

e.g. properties.name

An example of a filter expression will look like the following for the above trait and property filters when put together:

{
   "eqFilters":[
      {
         "name":"attributes.Fur Colour",
         "value":"Freedom"
      },
      {
         "name":"properties.name",
         "value":"Bob"
      }
   ],
   "rangeFilters":[
      {
         "name":"attributes.age",
         "value":[
            3,
            10
         ]
      }
   ]
}

React

import React from 'react'
import { useAccount } from 'wagmi'
import { ChainAddress } from '@fv-asset-registry/common'
import { useAssets } from '@futureverse/asset-register-react'
import { useFuturePassAccountAddress } from '@futureverse/react'

// React component to render all collectibles owned by a FuturePass user logged in.
export const AssetList = () => {
  // Get EOA address
  const { address } = useAccount()
  // Get FV address
  const { data: fpAccount } = useFuturePassAccountAddress()
  const {
    assets
  } = useAssets(
    {
      first: 1000,
      addresses: [address as ChainAddress, fpAccount as ChainAddress],
      filter: {
        eqFilters: [
          {
            name: "attributes.Fur Colour",
            value: "Freedom"
          }
        ],
        rangeFilters: [
          {
            name: "attributes.age",
            value: [3, 10]
          }
        ],
        search: "Blue"
      }
    },
    { enabled: !!fpAccount && !!address },
  )
  if (!assets) {
    return null
  }

  return (
    <div>
      {assets.map((asset) => <Asset key={asset.id} asset={asset} />)}
    </div>
  )

Node.JS

import { AssetRegister } from '@futureverse/asset-register'
const ar = new AssetRegister({
    ...
})

const assets = await ar.assets({
    addresses: [
        "0x2D2438C6281B5115733287fC279f854c868D3ee2",
        "0xFFFFFfFF00000000000000000000000000000417"
    ],
    collectionIds: [
        "7672:root:1234",
        "7672:root:2341",
    ],
    filter: {
        eqFilters: [
            {
                name: "attributes.Fur Colour",
                value: "Freedom"
            }
        ],
        rangeFilters: [
            {
                name: "attributes.age",
                value: [3, 10]
            }
        ],
        search: "Blue"
    }
})

GraphQL

query GetAssets($addresses: [ChainAddress!]!, $collectionIds: [CollectionId!], $after: String, $first: Float) {
  assets(
    addresses: $addresses
    collectionIds: $collectionIds
    after: $after
    first: $first
  ) {
    pageInfo {
      endCursor
      hasNextPage
    }
    edges {
      node {
        id
        collectionId
        tokenId
        assetType
        assetTree {
          data
          nodeId
        }
        schema {
          name
          namespace
          schema
          version
        }
        ownership {
          __typename
          ... on SFTAssetOwnership {
            id
            balancesOf(addresses: $addresses) {
              balance
              owner {
                address
              }
            }
          }
          ... on NFTAssetOwnership {
            owner {
              address
            }
          }
        }
        metadata {
          attributes
          properties
          uri
        }
        links {
          __typename
          ... on SFTAssetLink {
            parentLinks(addresses: $addresses) {
              collectionId
              tokenId
            }
          }
          ... on NFTAssetLink {
            parentLink {
              collectionId
              tokenId
            }
          }
        }
        collection {
          id
          chainId
          chainType
          location
          name
        }
      }
    }
  }
}