Skip to content

Commit 1925976

Browse files
authored
Merge pull request #203 from stackql/feature/doc-updates
anthropic updates
2 parents ec6754f + 6bb37aa commit 1925976

File tree

2 files changed

+255
-46
lines changed
  • docs/anthropic-docs/providers/anthropic/messages

2 files changed

+255
-46
lines changed

docs/anthropic-docs/providers/anthropic/messages/claude_35_chat/index.md

Lines changed: 0 additions & 43 deletions
This file was deleted.

docs/anthropic-docs/providers/anthropic/messages/message/index.md

Lines changed: 255 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,6 @@ image: /img/providers/anthropic/stackql-anthropic-provider-featured-image.png
1717

1818
import CopyableCode from '@site/src/components/CopyableCode/CopyableCode';
1919

20-
21-
22-
2320
## Overview
2421
<table><tbody>
2522
<tr><td><b>Name</b></td><td><code>message</code></td></tr>
@@ -38,7 +35,262 @@ import CopyableCode from '@site/src/components/CopyableCode/CopyableCode';
3835
| <CopyableCode code="stop_sequence" /> | `string` | The stop sequence that caused the model to stop, if applicable. |
3936
| <CopyableCode code="type" /> | `string` | Object type, which is always "message" for Messages API. |
4037
| <CopyableCode code="usage" /> | `object` | Information about token usage and rate limits. |
38+
4139
## Methods
4240
| Name | Accessible by | Required Params |
4341
|:-----|:--------------|:----------------|
4442
| <CopyableCode code="create_message" /> | `SELECT` | <CopyableCode code="anthropic-version, data__max_tokens, data__messages, data__model" /> |
43+
44+
## Required Parameters for Message Creation
45+
| Parameter | Description |
46+
|:----------|:------------|
47+
| `anthropic-version` | API version string (e.g., '2023-06-01') |
48+
| `data__max_tokens` | Maximum number of tokens to generate |
49+
| `data__messages` | Array of message objects with role and content |
50+
| `data__model` | Model identifier (e.g., 'claude-3-5-sonnet-20240620') |
51+
52+
:::info Model Comparison Table
53+
To help you choose the right model for your needs, we’ve compiled a table comparing the key features and capabilities of each model in the Claude family:
54+
55+
| Model | Claude 3.5 Sonnet | Claude 3 Opus | Claude 3 Sonnet | Claude 3 Haiku |
56+
|-----------------------|---------------------------------------|-----------------------------|-----------------------------|----------------------------------------------|
57+
| **Description** | Most intelligent model | Powerful model for highly complex tasks | Balance of intelligence and speed | Fastest and most compact model for near-instant responsiveness |
58+
| **Strengths** | Highest level of intelligence and capability | Top-level performance, intelligence, fluency, and understanding | Strong utility, balanced for scaled deployments | Quick and accurate targeted performance |
59+
| **Multilingual** | Yes | Yes | Yes | Yes |
60+
| **Vision** | Yes | Yes | Yes | Yes |
61+
| **Message Batches API** | Yes | Yes | No | Yes |
62+
| **API model name** | Upgraded version: `claude-3-5-sonnet-20241022` <br> Previous version: `claude-3-5-sonnet-20240620` | `claude-3-opus-20240229` | `claude-3-sonnet-20240229` | `claude-3-haiku-20240307` |
63+
| **Comparative latency** | Fast | Moderately fast | Fast | Fastest |
64+
| **Context window** | 200K | 200K | 200K | 200K |
65+
| **Max output** | 8192 tokens | 4096 tokens | 4096 tokens | 4096 tokens |
66+
| **Cost (Input / Output per MTok)** | $3.00 / $15.00 | $15.00 / $75.00 | $3.00 / $15.00 | $0.25 / $1.25 |
67+
| **Training data cut-off** | Apr 2024 | Aug 2023 | Aug 2023 | Aug 2023 |
68+
69+
:::
70+
71+
## Query Examples
72+
73+
### Basic Message Generation
74+
This example generates a one-sentence summary of StackQL:
75+
76+
```sql
77+
SELECT
78+
model as model,
79+
role as role,
80+
stop_reason as stop_reason,
81+
stop_sequence as stop_sequence,
82+
JSON_EXTRACT(usage, '$.input_tokens') as input_tokens,
83+
JSON_EXTRACT(usage, '$.output_tokens') as output_tokens,
84+
JSON_EXTRACT(json_each.value, '$.text') as content
85+
FROM
86+
anthropic.messages.message,
87+
JSON_EACH(content)
88+
WHERE
89+
"anthropic-version" = '2023-06-01'
90+
AND data__model = 'claude-3-5-sonnet-20240620'
91+
AND data__max_tokens = 1024
92+
AND data__messages = '[{"role": "user", "content": "one sentence summary of stackql"}]'
93+
```
94+
95+
Example response:
96+
```
97+
|----------------------------|-----------|-------------|---------------|--------------|---------------|--------------------------------|
98+
| model | role | stop_reason | stop_sequence | input_tokens | output_tokens | content |
99+
|----------------------------|-----------|-------------|---------------|--------------|---------------|--------------------------------|
100+
| claude-3-5-sonnet-20240620 | assistant | end_turn | null | 13 | 46 | StackQL is a SQL-like query |
101+
| | | | | | | language and runtime for |
102+
| | | | | | | cloud infrastructure, allowing |
103+
| | | | | | | users to query, analyze, and |
104+
| | | | | | | manage cloud resources across |
105+
| | | | | | | multiple providers using |
106+
| | | | | | | familiar SQL syntax. |
107+
|----------------------------|-----------|-------------|---------------|--------------|---------------|--------------------------------|
108+
```
109+
110+
### Multi-turn Conversation Example
111+
This example shows how to conduct a multi-turn conversation:
112+
113+
```sql
114+
SELECT
115+
JSON_EXTRACT(json_each.value, '$.text') as content
116+
FROM
117+
anthropic.messages.message,
118+
JSON_EACH(content)
119+
WHERE
120+
"anthropic-version" = '2023-06-01'
121+
AND data__model = 'claude-3-5-sonnet-20240620'
122+
AND data__max_tokens = 1024
123+
AND data__messages = '[
124+
{"role": "user", "content": "What is cloud infrastructure?"},
125+
{"role": "assistant", "content": "Cloud infrastructure refers to the hardware and software components needed for cloud computing, including servers, storage, and networking resources."},
126+
{"role": "user", "content": "How can StackQL help manage it?"}
127+
]'
128+
```
129+
130+
### Using System Prompts
131+
Example showing how to include a system prompt:
132+
133+
```sql
134+
SELECT
135+
JSON_EXTRACT(json_each.value, '$.text') as content
136+
FROM
137+
anthropic.messages.message,
138+
JSON_EACH(content)
139+
WHERE
140+
"anthropic-version" = '2023-06-01'
141+
AND data__model = 'claude-3-5-sonnet-20240620'
142+
AND data__max_tokens = 1024
143+
AND data__system = 'You are a cloud infrastructure expert focusing on technical details.'
144+
AND data__messages = '[{"role": "user", "content": "Explain how StackQL helps with cloud resource management"}]'
145+
```
146+
147+
## Usage Notes
148+
149+
### Token Usage
150+
- The `usage` object contains information about token consumption:
151+
- `input_tokens`: Number of tokens in the input
152+
- `output_tokens`: Number of tokens generated in the response
153+
- Token usage affects billing and rate limits
154+
- Token counts may not exactly match visible content due to internal processing
155+
156+
### Response Processing
157+
- Use `JSON_EACH` to process the content array
158+
- Content is returned as blocks with type and text
159+
- Use `JSON_EXTRACT` to access nested JSON fields like usage statistics
160+
161+
### Best Practices
162+
1. Always specify an appropriate `max_tokens` value
163+
2. Include the correct `anthropic-version` header
164+
3. Format message arrays properly as JSON strings
165+
4. Use system prompts for specialized behavior
166+
5. Monitor token usage for cost optimization
167+
168+
## Error Handling
169+
Common error scenarios to handle:
170+
- Invalid model specification
171+
- Malformed message JSON
172+
- Token limit exceeded
173+
- Rate limiting
174+
- Authentication failures
175+
176+
## Rate Limits
177+
- Token-based rate limiting
178+
- Monitored through the usage object
179+
- Consider implementing backoff strategies for heavy usage
180+
181+
## Version Compatibility
182+
- Specify API version using `anthropic-version`
183+
- Current supported version: '2023-06-01'
184+
- Check Anthropic's documentation for version updates
185+
186+
## Advanced Usage Examples
187+
188+
### Temperature Control
189+
Adjust response randomness with the temperature parameter:
190+
191+
```sql
192+
/* Lower temperature for more focused responses */
193+
SELECT
194+
JSON_EXTRACT(json_each.value, '$.text') as content
195+
FROM
196+
anthropic.messages.message,
197+
JSON_EACH(content)
198+
WHERE
199+
"anthropic-version" = '2023-06-01'
200+
AND data__model = 'claude-3-5-sonnet-20240620'
201+
AND data__max_tokens = 1024
202+
AND data__temperature = 1
203+
AND data__messages = '[{"role": "user", "content": "List 3 key benefits of using StackQL"}]'
204+
```
205+
206+
### Using Stop Sequences
207+
Configure custom stop sequences to control response length:
208+
209+
```sql
210+
SELECT
211+
JSON_EXTRACT(json_each.value, '$.text') as content,
212+
stop_reason,
213+
stop_sequence
214+
FROM
215+
anthropic.messages.message,
216+
JSON_EACH(content)
217+
WHERE
218+
"anthropic-version" = '2023-06-01'
219+
AND data__model = 'claude-3-5-sonnet-20240620'
220+
AND data__max_tokens = 1024
221+
AND data__stop_sequences = '["END", "STOP"]'
222+
AND data__messages = '[{"role": "user", "content": "Describe StackQL until you reach a natural conclusion END"}]'
223+
```
224+
225+
### Metadata Tracking
226+
Include metadata for request tracking:
227+
228+
```sql
229+
SELECT
230+
JSON_EXTRACT(json_each.value, '$.text') as content,
231+
JSON_EXTRACT(usage, '$.input_tokens') as input_tokens,
232+
JSON_EXTRACT(usage, '$.output_tokens') as output_tokens
233+
FROM
234+
anthropic.messages.message,
235+
JSON_EACH(content)
236+
WHERE
237+
"anthropic-version" = '2023-06-01'
238+
AND data__model = 'claude-3-5-sonnet-20240620'
239+
AND data__max_tokens = 1024
240+
AND data__metadata = '{"user_id": "u123"}'
241+
AND data__messages = '[{"role": "user", "content": "What is StackQL?"}]'
242+
```
243+
244+
## Working with Response Data
245+
246+
### Content Block Structure
247+
The content field returns an array of blocks with this structure:
248+
249+
```json
250+
{
251+
"type": "text",
252+
"text": "The actual content..."
253+
}
254+
```
255+
256+
Access specific parts using JSON functions:
257+
```sql
258+
-- Get just the text content
259+
JSON_EXTRACT(json_each.value, '$.text')
260+
261+
-- Get the content type
262+
JSON_EXTRACT(json_each.value, '$.type')
263+
```
264+
265+
### Usage Statistics Processing
266+
Extract detailed usage information:
267+
268+
```sql
269+
SELECT
270+
JSON_EXTRACT(usage, '$.input_tokens') as input_tokens,
271+
JSON_EXTRACT(usage, '$.output_tokens') as output_tokens,
272+
JSON_EXTRACT(usage, '$.cache_creation_input_tokens') as cache_creation_tokens,
273+
JSON_EXTRACT(usage, '$.cache_read_input_tokens') as cache_read_tokens
274+
FROM
275+
anthropic.messages.message
276+
WHERE
277+
-- query conditions
278+
```
279+
280+
## Performance Optimization
281+
282+
### Token Usage Optimization
283+
Tips for minimizing token usage:
284+
1. Use precise prompts
285+
2. Set appropriate max_tokens
286+
3. Use system prompts effectively
287+
4. Leverage stop sequences
288+
5. Monitor and analyze usage patterns
289+
290+
### Response Processing Optimization
291+
Strategies for efficient response handling:
292+
1. Use appropriate JSON extraction
293+
2. Implement efficient error handling
294+
3. Process responses asynchronously when possible
295+
4. Cache frequently used responses
296+
5. Implement retry logic with exponential backoff

0 commit comments

Comments
 (0)