Skip to content

Commit b345cc1

Browse files
catalyst17catalyst17
committed
docs: add docs on aggregates (#7201)
# [Portal] Feature: Add Aggregation Examples and Documentation to Insight ## Notes for the reviewer This PR adds comprehensive documentation for the Insight aggregation functionality across multiple pages: - Added an "Aggregation Examples" section to the LLMs page with code samples - Added detailed aggregation documentation to the Agents and LLMs page - Added aggregation examples to the Blueprints page for Events, Transactions, Wallet Transactions, and Blocks - Added FAQs about aggregation queries - Added "Using Aggregation Presets" section to the Get Started page - Enhanced Use Cases page with example aggregations for relevant scenarios ## How to test Review the documentation for clarity and accuracy. The examples should be consistent with the actual API functionality. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Added comprehensive examples and explanations for using aggregation functions in Insight API queries across multiple documentation sections, including blueprints, use cases, FAQs, and getting started guides. - Introduced new sections detailing aggregation presets, usage patterns, and code snippets for blockchain data analysis. - Enhanced clarity on performing statistical and summary queries, with guidance on leveraging the Insight Playground for interactive exploration. - Updated the Insight landing page with a new feature card highlighting powerful aggregation capabilities and improved layout for feature cards. <!-- end of auto-generated comment: release notes by coderabbit.ai --> <!-- start pr-codex --> --- ## PR-Codex overview This PR enhances the documentation for the `Insight` tool by adding new aggregation features, examples, and updating existing content to clarify how to utilize these functionalities effectively. ### Detailed summary - Added `FunctionSquareIcon` to the import statement in `page.mdx`. - Updated grid layout class from `lg:grid-cols-2` to `lg:grid-cols-3` in `page.mdx`. - Introduced a new `FeatureCard` titled "Powerful Aggregations" in `page.mdx`. - Added sections on aggregation queries and examples in `faqs/page.mdx`, `get-started/page.mdx`, and `agents-and-llms/page.mdx`. - Provided aggregation examples in `use-cases/page.mdx` and `blueprints/page.mdx`. - Enhanced documentation for wallet transactions and blocks, including aggregation examples in `agents-and-llms/page.mdx`. > ✨ Ask PR-Codex anything about this PR by commenting with `/codex {your question}` <!-- end pr-codex -->
1 parent 3d3c6f3 commit b345cc1

File tree

7 files changed

+334
-9
lines changed

7 files changed

+334
-9
lines changed

‎apps/portal/src/app/insight/agents-and-llms/llmstxt/page.mdx‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,64 @@ Insight is a powerful tool that lets you retrieve blockchain data from any EVM c
3434

3535
- **Response Processing**: Some numeric values are returned as strings to maintain precision. Convert them appropriately in your application.
3636

37+
## Aggregation Examples
38+
39+
Insight supports various aggregation functions that can be used to analyze blockchain data. Here are some common examples:
40+
41+
### Basic Aggregations
42+
43+
```typescript
44+
// Count all transactions
45+
const count = await fetch('https://10.insight.thirdweb.com/v1/transactions?aggregate=count() AS transaction_count');
46+
47+
// Get total value transferred (in wei)
48+
const totalValue = await fetch('https://10.insight.thirdweb.com/v1/transactions?aggregate=sum(value) AS total_value_wei');
49+
50+
// Get average gas used
51+
const avgGas = await fetch('https://10.insight.thirdweb.com/v1/transactions?aggregate=avg(gas_used) AS avg_gas_used');
52+
```
53+
54+
### Wallet-Specific Aggregations
55+
56+
```typescript
57+
// Get wallet transaction count and total value
58+
const walletStats = await fetch(
59+
'https://10.insight.thirdweb.com/v1/wallets/0x123.../transactions?aggregate=count() AS transaction_count&aggregate=sum(value) AS total_value_wei'
60+
);
61+
62+
// Calculate total fees paid by a wallet
63+
const walletFees = await fetch(
64+
'https://10.insight.thirdweb.com/v1/wallets/0x123.../transactions?aggregate=sum(gas_used * gas_price) AS total_fees_wei'
65+
);
66+
```
67+
68+
### Block Data Aggregations
69+
70+
```typescript
71+
// Get block statistics
72+
const blockStats = await fetch(
73+
'https://10.insight.thirdweb.com/v1/blocks?aggregate=sum(transaction_count) AS total_transactions&aggregate=avg(transaction_count) AS avg_transactions_per_block'
74+
);
75+
76+
// Get block range
77+
const blockRange = await fetch(
78+
'https://10.insight.thirdweb.com/v1/blocks?aggregate=min(number) AS min_block_number&aggregate=max(number) AS max_block_number'
79+
);
80+
```
81+
82+
### Filtering with Aggregations
83+
84+
```typescript
85+
// Get transaction stats for a specific time period
86+
const txStats = await fetch(
87+
'https://10.insight.thirdweb.com/v1/transactions?aggregate=count() AS transaction_count&aggregate=sum(value) AS total_value_wei&filter_timestamp_gte=2024-01-01&filter_timestamp_lte=2024-01-31'
88+
);
89+
90+
// Get block metrics for recent blocks
91+
const recentBlocks = await fetch(
92+
'https://10.insight.thirdweb.com/v1/blocks?aggregate=sum(transaction_count) AS total_transactions&filter_number_gte=18000000'
93+
);
94+
```
3795

3896
## API URL
3997

‎apps/portal/src/app/insight/agents-and-llms/page.mdx‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -190,6 +190,100 @@ async function getNFTBalances(ownerAddress: string) {
190190
}
191191
```
192192

193+
### Aggregations
194+
195+
Insight supports powerful aggregation functions that can be used to analyze blockchain data. Here's how to use them:
196+
197+
```typescript
198+
// Basic aggregation structure
199+
const response = await fetch(
200+
'https://{{chainId}}.insight.thirdweb.com/v1/endpoint?aggregate=function(field) AS alias',
201+
{ headers: { 'x-client-id': '{{clientId}}' } }
202+
);
203+
204+
// Multiple aggregations in one request
205+
const response = await fetch(
206+
'https://{{chainId}}.insight.thirdweb.com/v1/endpoint?aggregate=count() AS total&aggregate=sum(value) AS total_value',
207+
{ headers: { 'x-client-id': '{{clientId}}' } }
208+
);
209+
210+
// With filters
211+
const response = await fetch(
212+
'https://{{chainId}}.insight.thirdweb.com/v1/transactions?aggregate=count() AS tx_count&filter_timestamp_gte=2024-01-01',
213+
{ headers: { 'x-client-id': '{{clientId}}' } }
214+
);
215+
```
216+
217+
#### Aggregation Presets available in the playground as examples
218+
219+
1. **Default Aggregations**
220+
- `count() AS count_all` - Count all items
221+
- `sum(gas_used) AS total_gas_used` - Total gas used
222+
- `avg(gas_used) AS avg_gas_used` - Average gas used
223+
- `min(gas_used) AS min_gas_used` - Minimum gas used
224+
- `max(gas_used) AS max_gas_used` - Maximum gas used
225+
- `countDistinct(column_name) AS unique_count` - Count distinct values
226+
227+
2. **Events Specific**
228+
- `count() AS event_count` - Count events
229+
- `countDistinct(address) AS unique_addresses` - Unique addresses
230+
- `min(block_number) AS min_block` - Minimum block number
231+
- `max(block_number) AS max_block` - Maximum block number
232+
233+
3. **Transactions Specific**
234+
- `count() AS transaction_count` - Count transactions
235+
- `sum(value) AS total_value_wei` - Total value transferred
236+
- `sum(gas_used) AS total_gas_used` - Total gas used
237+
- `avg(value) AS avg_value_wei` - Average value
238+
- `avg(gas_used) AS avg_gas_used` - Average gas used
239+
- `countDistinct(from_address) AS unique_senders` - Unique senders
240+
- `countDistinct(to_address) AS unique_receivers` - Unique receivers
241+
242+
4. **Wallet Transactions**
243+
- `count() AS transaction_count` - Transaction count
244+
- `sum(value) AS total_value_wei` - Total value
245+
- `avg(value) AS avg_value_wei` - Average value
246+
- `sum(gas_used * gas_price) AS total_fees_wei` - Total fees
247+
248+
5. **Blocks Specific**
249+
- `sum(transaction_count) AS total_transactions` - Total transactions
250+
- `avg(transaction_count) AS avg_transactions_per_block` - Avg tx/block
251+
- `sum(gas_used) AS total_gas_used` - Total gas used
252+
- `min(number) AS min_block_number` - Min block number
253+
- `max(number) AS max_block_number` - Max block number
254+
255+
#### Common Aggregation Examples
256+
257+
```typescript
258+
// 1. Get transaction statistics
259+
const txStats = await fetch(
260+
'https://{{chainId}}.insight.thirdweb.com/v1/transactions?aggregate=count() AS transaction_count&aggregate=sum(value) AS total_value_wei&aggregate=avg(gas_used) AS avg_gas_used',
261+
{ headers: { 'x-client-id': '{{clientId}}' } }
262+
);
263+
264+
// 2. Get wallet transaction stats
265+
const walletStats = await fetch(
266+
'https://{{chainId}}.insight.thirdweb.com/v1/wallets/0x123.../transactions?aggregate=count() AS transaction_count&aggregate=sum(value) AS total_value_wei&aggregate=sum(gas_used * gas_price) AS total_fees_wei',
267+
{ headers: { 'x-client-id': '{{clientId}}' } }
268+
);
269+
```
270+
271+
#### Filtering with Aggregations
272+
273+
```typescript
274+
// Get transaction stats for a specific time period
275+
const txStats = await fetch(
276+
'https://{{chainId}}.insight.thirdweb.com/v1/transactions?aggregate=count() AS transaction_count&aggregate=sum(value) AS total_value_wei&filter_timestamp_gte=2024-01-01&filter_timestamp_lte=2024-01-31',
277+
{ headers: { 'x-client-id': '{{clientId}}' } }
278+
);
279+
280+
// Get block metrics for recent blocks
281+
const blockStats = await fetch(
282+
'https://{{chainId}}.insight.thirdweb.com/v1/blocks?aggregate=sum(transaction_count) AS total_transactions&aggregate=avg(transaction_count) AS avg_transactions_per_block&filter_number_gte=18000000',
283+
{ headers: { 'x-client-id': '{{clientId}}' } }
284+
);
285+
```
286+
193287
### Using Filters
194288

195289
```typescript

‎apps/portal/src/app/insight/blueprints/page.mdx‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,32 @@ Blockchain events offers developers a powerful way to track and analyze blockcha
3535
| Block Number | The `block_number` indicates the position of the block in the blockchain. It tells you when (in terms of blockchain sequence) the event occurred. | Block number 12,345,678 on Ethereum might contain transactions from a particular moment, such as the transfer of 10 ETH between two accounts. You can think of block numbers like page numbers in a ledger.
3636
| Block Timestamp | The `block_timestamp` is the exact time when the block was mined and added to the blockchain. | If block 12,345,678 was mined on July 1, 2023, at 12:30 PM UTC, the timestamp will reflect this exact moment. This helps you pinpoint when an event, such as a token transfer, actually happened in real time.
3737

38+
### Aggregations Examples
39+
40+
#### Get Event Statistics
41+
```typescript
42+
// Get total event count and unique addresses
43+
const response = await fetch(
44+
'https://1.insight.thirdweb.com/v1/events?aggregate=count() AS event_count&aggregate=countDistinct(address) AS unique_addresses'
45+
);
46+
```
47+
48+
#### Track Collection Activity
49+
```typescript
50+
// Get min/max block numbers and unique topics
51+
const response = await fetch(
52+
'https://1.insight.thirdweb.com/v1/events?aggregate=min(block_number) AS min_block&aggregate=max(block_number) AS max_block&aggregate=countDistinct(topic0) AS unique_topics'
53+
);
54+
```
55+
56+
#### Custom Aggregations
57+
```typescript
58+
// Custom aggregations for specific analysis
59+
const response = await fetch(
60+
'https://1.insight.thirdweb.com/v1/events?aggregate=count() AS transfers&aggregate=countDistinct(from_address) AS unique_senders&aggregate=countDistinct(to_address) AS unique_recipients'
61+
);
62+
```
63+
3864
## Transactions Blueprint
3965

4066
Transaction data equips developers with the tools they need to interact with blockchain data efficiently and effectively. By providing clear, actionable insights into each transaction, the API helps streamline tasks like monitoring smart contract interactions, tracking asset transfers, and debugging. Developers can rely on this endpoint to access essential transaction details, enabling faster troubleshooting and more informed decision-making. Whether building DeFi platforms, dApps, or blockchain-based analytics tools, transaction data is the essence for all interactions with any chains.
@@ -62,6 +88,67 @@ Transaction data equips developers with the tools they need to interact with blo
6288
| Block Timestamp | This is the exact time when the block containing the transaction was mined and added to the blockchain. | If the transaction was confirmed on July 1, 2023, at 12:30 PM UTC, the block timestamp will reflect this moment. It's useful for analyzing when specific activities (like token transfers) occurred.
6389
| r, s, v | These are the cryptographic components of the transaction signature. They prove that the transaction was signed by the private key associated with the sender's address. | The `r`, `s`, and `v` values are produced during the signing process and are necessary to verify the authenticity of the transaction on the blockchain.
6490

91+
### Aggregations Examples
92+
93+
#### Get Transaction Statistics
94+
```typescript
95+
// Get total transaction count and total value transferred
96+
const response = await fetch(
97+
'https://1.insight.thirdweb.com/v1/transactions?aggregate=count() AS transaction_count&aggregate=sum(value) AS total_value'
98+
);
99+
```
100+
101+
#### Analyze Gas Usage
102+
```typescript
103+
// Get average and max gas used
104+
const response = await fetch(
105+
'https://1.insight.thirdweb.com/v1/transactions?aggregate=avg(gas_used) AS avg_gas&aggregate=max(gas_used) AS max_gas'
106+
);
107+
```
108+
109+
## Wallet Transactions Blueprint
110+
111+
The Wallet Transactions Blueprint provides detailed transaction history for specific wallet addresses, making it easy to track all activities associated with a particular address.
112+
113+
### Aggregation Examples
114+
115+
#### Get Wallet Summary
116+
```typescript
117+
// Get total transaction count and total value for a wallet
118+
const response = await fetch(
119+
'https://1.insight.thirdweb.com/v1/wallets/0x123.../transactions?aggregate=count() AS transaction_count&aggregate=sum(value) AS total_value'
120+
);
121+
```
122+
123+
#### Calculate Total Fees Paid
124+
```typescript
125+
// Calculate total fees paid by a wallet
126+
const response = await fetch(
127+
'https://1.insight.thirdweb.com/v1/wallets/0x123.../transactions?aggregate=sum(gas_used * gas_price) AS total_fees'
128+
);
129+
```
130+
131+
## Blocks Blueprint
132+
133+
The Blocks Blueprint provides access to blockchain block data, including block details, transaction counts, and gas usage statistics.
134+
135+
### Aggregation Examples
136+
137+
#### Get Block Statistics
138+
```typescript
139+
// Get total block count and total transactions
140+
const response = await fetch(
141+
'https://1.insight.thirdweb.com/v1/blocks?aggregate=count() AS block_count&aggregate=sum(transaction_count) AS total_transactions'
142+
);
143+
```
144+
145+
#### Analyze Block Metrics
146+
```typescript
147+
// Get average transactions per block and total gas used
148+
const response = await fetch(
149+
'https://1.insight.thirdweb.com/v1/blocks?aggregate=avg(transaction_count) AS avg_transactions&aggregate=sum(gas_used) AS total_gas_used'
150+
);
151+
```
65152

66153
## Tokens Blueprint
67154

‎apps/portal/src/app/insight/faqs/page.mdx‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,30 @@
11
# Insight FAQs
22

3+
## Aggregation Queries
4+
5+
### How do I use aggregations in my queries?
6+
You can include aggregation functions directly in your API requests. Here's an example:
7+
```typescript
8+
// Get total transaction value and average gas used
9+
const response = await fetch(
10+
'https://10.insight.thirdweb.com/v1/transactions?aggregate=count() AS transaction_count&aggregate=sum(value) AS total_value_wei&aggregate=avg(gas_used) AS avg_gas_used'
11+
);
12+
```
13+
14+
### Where can I find examples of using aggregations?
15+
You can find working examples and experiment with different aggregation presets in the Insight Playground. The Playground provides a user-friendly interface to build and test your aggregation queries.
16+
17+
### What are some common use cases for aggregations?
18+
- Calculating total trading volume
19+
- Finding average transaction values
20+
- Counting unique users/wallets
21+
- Analyzing gas usage patterns
22+
- Tracking NFT collection statistics
23+
24+
### Can I create custom aggregations?
25+
Yes, you can create custom aggregations using standard SQL aggregation functions like `count()`, `sum()`, `avg()`, `min()`, `max()`, and `countDistinct()`. The presets are just convenient shortcuts for common operations.
26+
27+
### Where can I learn more about available presets?
28+
You can find the complete list of available aggregation presets in the Insight Playground, where you can also test them with real blockchain data.
29+
330
More information coming soon.

‎apps/portal/src/app/insight/get-started/page.mdx‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,60 @@ Once you execute the query above you will receive a result similar to this:
139139
}
140140
```
141141

142+
## Using Aggregations
143+
144+
Insight provides several predefined aggregation presets that make it easy to analyze your blockchain data. These presets are available in the Insight Playground, where you can experiment with them using a user-friendly interface.
145+
146+
### Example: Get Transaction Statistics
147+
148+
```typescript
149+
const getTransactionStats = async () => {
150+
try {
151+
const response = await fetch(
152+
'https://1.insight.thirdweb.com/v1/transactions?aggregate=count() AS transaction_count&aggregate=sum(value) AS total_value&aggregate=avg(gas_used) AS avg_gas',
153+
{
154+
headers: {
155+
'x-client-id': '<YOUR_THIRDWEB_CLIENT_ID>'
156+
}
157+
}
158+
);
159+
const stats = await response.json();
160+
return stats;
161+
} catch (error) {
162+
console.error('Error:', error);
163+
}
164+
};
165+
```
166+
167+
### Example: Get Block Metrics
168+
169+
```typescript
170+
const getBlockMetrics = async () => {
171+
try {
172+
const response = await fetch(
173+
'https://1.insight.thirdweb.com/v1/blocks?aggregate=count() AS block_count&aggregate=sum(transaction_count) AS total_transactions&aggregate=avg(transaction_count) AS avg_transactions',
174+
{
175+
headers: {
176+
'x-client-id': '<YOUR_THIRDWEB_CLIENT_ID>'
177+
}
178+
}
179+
);
180+
const metrics = await response.json();
181+
return metrics;
182+
} catch (error) {
183+
console.error('Error:', error);
184+
}
185+
};
186+
```
187+
188+
### Explore in the Playground
189+
190+
For a more interactive experience, try out the aggregation presets in the Insight Playground. The Playground allows you to:
191+
- Browse available presets for each endpoint
192+
- See real-time results
193+
- Generate code snippets for your application
194+
- Test different aggregation combinations
195+
142196
## Multichain Queries
143197

144198
Insight also supports querying multiple chains in a single API call. This is useful when you need to retrieve data across different networks without making separate requests.

0 commit comments

Comments
 (0)