Arweave Query Guide

ARWEAVE.GQL.MD

Arweave GraphQL Guide

Retrieving Data

In order to retrieve data from Arweave, you can use the following example query to retrieve the entire transaction output.

query {
    transactions {
        cursor
        edges {
            node {
                id
                anchor
                signature
                recipient
                owner {
                    address
                    key
                }
                fee {
                    winston
                    ar
                }
                quantity {
                    winston
                    ar
                }
                data {
                    size
                    type
                }
                tags {
                    name
                    value
                }
                block {
                    id
                    timestamp
                    height
                    previous
                }
                parent {
                    id
                }
            }
        }
    }
}

Here are some example use cases that you might prefer using GraphQL for.

Retrieve the block id only

query {
    transactions {
        edges {
            node {
                id
            }
        }
    }
}

Retrieve the tags for each block

query {
    transactions {
        edges {
            node {
                id
                tags {
                    name
                    value
                }
            }
        }
    }
}

Retrieve the block data

query {
    transactions {
        edges {
            node {
                block {
                    id
                    timestamp
                    height
                    previous
                }
            }
        }
    }
}

Retrieve AR payment transaction data

query {
    transactions {
        edges {
            node {
                id
                recipient
                owner {
                    address
                    key
                }
                fee {
                    winston
                    ar
                }
                quantity {
                    winston
                    ar
                }
            }
        }
    }
}

Querying

There are several arguments you can use to query the Arweave database.

By transaction id. Provide the blockhash to retrieve the block.

query {
    transactions(ids: ["G-1t0Lqysin897HC3IV8xu_Mr884B-Mo5YEnlhUH54k"]) {
        edges {
            node {
                id
            }
        }
    }
}

By recipients. Provide the address to retrieve all the transactions where the account received AR.

query {
    transactions(recipients:["M6w588ZkR8SVFdPkNXdBy4sqbMN0Y3F8ZJUWm2WCm8M"]) {
        edges {
            node {
                id
            }
        }
    }
}

By tags. Provide the tag name and value to retrieve all transactions associated with that value.

Single tag filter.

query {
    transactions(
        tags: {
            name: "Content-Type",
            values: ["text/html"]
        }
    ) {
        edges {
            node {
                id
            }
        }
    }
}

Multi tag filter.

query {
    transactions(
        tags: [
            {
                name: "Content-Type",
                values: ["text/html"]
            },
            {
                name: "User-Agent",
                values: ["ArweaveAutoDPL/0.1"]
            }
        ]
    ) {
        edges {
            node {
                id
            }
        }
    }
}

With pagination. Provide the n amount of entries and/or which block id to start from.

query {
    transactions(first: 5) {
        edges {
            node {
                id
            }
        }
    }
}

Or, with a cursor

query {
    transactions(first: 5, after: "WyIyMDIwLTA5LTIzVDE2OjQ0OjE0LjY5MloiLDFd") {
        edges {
            cursor # Make sure to get the edge cursor
            node {
                id
            }
        }
    }
}

Filtering a block range

query {
    transactions(block: {min: 0, max: 10}) {
        edges {
            node {
                id
            }
        }
    }
}

And finally, sorting

Descending (Newest first)

query {
  transactions(sort: HEIGHT_DESC) {
  	edges {
      cursor
      node {
        id
      }
    }
  }
}

Ascending (Oldest first)

query {
  transactions(sort: HEIGHT_ASC) {
  	edges {
      cursor
      node {
        id
      }
    }
  }
}

This is super helpful! One idea I had after reading this over would be to include an example or two with owner and/or recipients.

Absolutely!
I mentioned in Discord having an interactive guide where they upload blocks and then query with GraphQL.
I'd love to hear other examples I should add. Let's compile a list of important queries new users should learn! 💯

I also mentioned a wrapper library for GraphQL as part of arweave-js. Either way, we should be flexible making it accessible and easy to traverse Arweave with both GraphQL and a wrapper library!

@TheLoneRonin This is very helpful and timely, thank you!

I'm sure @johnletey might have some thoughts on other examples.

Awesome, well, let's compile examples we might want to have for a real documentation file.
I'm all ears.

@TheLoneRonin Thanks for compiling this 😄 Looking amazing so far.

I'll have an in-depth look at this, and leave some suggestions.

(Thanks for the ping @t8)

Is there a way to say give me tags with values > 20 for example?

Thanks for all gist.
May I ask what should I do with multiple tags filter then do pagination?
I've tried several ways but couldn't get it through.

transactions(first: 15) ( tags: [