Skip to content

Commit 2fe3c71

Browse files
VirajAgarwal1VirajAgarwal1
authored
Update README.md
1 parent 2cc608f commit 2fe3c71

File tree

1 file changed

+255
-74
lines changed

1 file changed

+255
-74
lines changed

‎tutorial/markdown/python/streamlit/README.md‎

Lines changed: 255 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -21,114 +21,295 @@ length: 30 Mins
2121

2222
# [Couchbase Connector for Streamlit](https://couchbase-st-tutorial.streamlit.app/)
2323

24-
## 1. Introduction
25-
This project provides a seamless integration between Streamlit and Couchbase, allowing developers to interact with Couchbase databases effortlessly. It enables users to fetch, insert, update, and delete data within Streamlit applications without needing to switch between different SDKs, enhancing the overall development experience.
26-
27-
For a working demo please checkout `src/Demo.py` file. You can run it by the command
28-
```bash
29-
git clone https://github.com/Couchbase-Ecosystem/couchbase_streamlit_connector.git
30-
cd ./couchbase_streamlit_connector
31-
pip install -r requirements.txt
32-
pip install plotly geopy numpy
33-
streamlit run src/Demo.py
34-
```
35-
Or you can jave a look at it through this link [Demo App](https://couchbase-connector-demo-app.streamlit.app/)
24+
## Introduction
25+
This comprehensive tutorial repository guides developers through integrating Couchbase with Streamlit applications. Unlike a simple demo app, this repository focuses on teaching the fundamentals, best practices, and interactive implementation of Couchbase within Streamlit applications.
26+
27+
## Table of Contents
28+
1. [Goals](#goals)
29+
2. [Prerequisites](#prerequisites)
30+
3. [Installation](#installation)
31+
4. [Core Concepts](#core-concepts)
32+
5. [Tutorial Sections](#tutorial-sections)
33+
6. [Running Your Application](#running-your-application)
34+
7. [Conclusion](#conclusion)
35+
8. [Appendix](#appendix)
36+
37+
## Goals
38+
- Master Couchbase integration with Streamlit applications
39+
- Understand core Couchbase concepts and their application in Streamlit
40+
- Learn through hands-on, working example
41+
42+
## Prerequisites
3643

37-
## 2. Prerequisites
3844
### System Requirements
39-
- Ensure you have **Python 3.10 or higher** (check [compatibility](https://docs.couchbase.com/python-sdk/current/project-docs/compatibility.html#python-version-compat) with the Couchbase SDK), a **Couchbase Capella account** ([Docs](https://docs.couchbase.com/cloud/get-started/intro.html)), and an **operational cluster** created in a project.
40-
- Configured cluster access permissions and allowed IP addresses ([Docs](https://docs.couchbase.com/cloud/get-started/connect.html#prerequisites))
41-
- Connection string obtained from Couchbase Capella
42-
43-
### Installing Dependencies
44-
To install the required dependencies, run:
45-
```sh
46-
pip install couchbase-streamlit-connector
47-
```
45+
- Python 3.10 or higher ([Compatibility Guide](https://docs.couchbase.com/python-sdk/current/project-docs/compatibility.html#python-version-compat))
46+
- Couchbase Capella account ([Get Started](https://docs.couchbase.com/cloud/get-started/intro.html))
47+
- Active Couchbase cluster with connection credentials
4848

49-
## 3. Usage Guide
49+
### Required Knowledge
50+
- Basic Python programming
51+
- Fundamental understanding of web applications
52+
- Basic database concepts
5053

51-
### Initializing the Connector
52-
You can set up the Couchbase connection using either of the following methods:
54+
## Installation
5355

54-
#### **Option 1: Using `secrets.toml` (Recommended)**
55-
For better security and convenience, store your credentials in a `.streamlit/secrets.toml` file at the root of your project. Learn more about [Streamlit Secrets Management](https://docs.streamlit.io/develop/concepts/connections/secrets-management):
56+
1. **Set up your Python environment**:
57+
```bash
58+
python -m venv venv
59+
source venv/bin/activate # On Windows: venv\Scripts\activate
60+
```
5661

57-
```toml
58-
[connections.couchbase]
59-
CONNSTR = "<CONNECTION_STRING>"
60-
USERNAME = "<CLUSTER_ACCESS_USERNAME>"
61-
PASSWORD = "<CLUSTER_ACCESS_PASSWORD>"
62-
BUCKET_NAME = "<BUCKET_NAME>"
63-
SCOPE_NAME = "<SCOPE_NAME>"
64-
COLLECTION_NAME = "<COLLECTION_NAME>"
65-
```
62+
2. **Install required packages**:
63+
```bash
64+
pip install streamlit couchbase-streamlit-connector
65+
```
6666

67-
Then, initialize the connection in your Streamlit application:
67+
## Core Concepts
6868

69-
```python
70-
import streamlit as st
71-
from couchbase_streamlit_connector.connector import CouchbaseConnector
69+
### Understanding JSON and Document Databases
70+
Couchbase is a NoSQL document database that stores data in JSON format. This section explains why this matters:
71+
72+
#### JSON Basics
73+
JSON (JavaScript Object Notation) is a lightweight data format that's:
74+
- Human-readable
75+
- Easy to parse and generate
76+
- Flexible for different data structures
7277

73-
connection = st.connection(
74-
"couchbase",
75-
type=CouchbaseConnector
76-
)
77-
st.help(connection)
78+
Example JSON document:
79+
```json
80+
{
81+
"id": "user_123",
82+
"name": "Alice Smith",
83+
"email": "[email protected]",
84+
"preferences": {
85+
"theme": "dark",
86+
"notifications": true
87+
}
88+
}
7889
```
7990

80-
#### **Option 2: Passing Credentials Directly (Alternative)**
81-
Alternatively, you can pass the connection details as keyword arguments:
91+
#### Why Couchbase Uses JSON
92+
- **Flexible Schema**: Adapt to changing data requirements
93+
- **Efficient Querying**: Native support for SQL-like queries (N1QL)
94+
- **Scalability**: Easy to distribute and replicate
95+
- **Natural Data Representation**: Matches application objects
96+
97+
### Couchbase Architecture Overview
98+
- **Buckets**: Top-level containers for data
99+
- **Scopes**: Namespaces within buckets
100+
- **Collections**: Groups of related documents
101+
- **Documents**: Individual JSON data records
102+
103+
### Important Operation Notes
104+
- **CRUD Operations**: Create, Read, Update, and Delete operations only work on the specific bucket, scope, and collection specified during connection setup.
105+
- **Queries**: Can work across any bucket, scope, and collection in the cluster, regardless of the connection settings.
106+
- **Access Control**: Both CRUD operations and queries are limited by the permissions assigned to the Couchbase user in the cluster.
107+
108+
## Tutorial Sections
82109

110+
### 1. Setting Up Your First Application
111+
112+
Create a new file `app.py`:
83113
```python
84114
import streamlit as st
115+
import json
85116
from couchbase_streamlit_connector.connector import CouchbaseConnector
86117

87-
connection = st.connection(
88-
"couchbase",
89-
type=CouchbaseConnector,
90-
CONNSTR="<CONNECTION_STRING>",
91-
USERNAME="<USERNAME>",
92-
PASSWORD="<PASSWORD>",
93-
BUCKET_NAME="<BUCKET_NAME>",
94-
SCOPE_NAME="<SCOPE_NAME>",
95-
COLLECTION_NAME="<COLLECTION_NAME>"
96-
)
97-
st.help(connection)
118+
def initialize_connection():
119+
st.title("Couchbase + Streamlit Application")
120+
121+
with st.sidebar:
122+
st.header("Connection Settings")
123+
# Connection configuration
124+
conn_str = st.text_input("Connection String")
125+
username = st.text_input("Username")
126+
password = st.text_input("Password", type="password")
127+
bucket_name = st.text_input("Bucket Name")
128+
scope_name = st.text_input("Scope Name")
129+
collection_name = st.text_input("Collection Name")
130+
131+
if st.button("Connect", key="connect_btn"):
132+
try:
133+
connection = st.connection(
134+
"couchbase",
135+
type=CouchbaseConnector,
136+
CONNSTR=conn_str,
137+
USERNAME=username,
138+
PASSWORD=password,
139+
BUCKET_NAME=bucket_name,
140+
SCOPE_NAME=scope_name,
141+
COLLECTION_NAME=collection_name
142+
)
143+
st.session_state["connection"] = connection
144+
st.success("Connected successfully!")
145+
except Exception as e:
146+
st.error(f"Connection failed: {e}")
98147
```
99148

100-
### Performing CRUD Operations
149+
### 2. Implementing CRUD Operations
150+
151+
#### Create Operation
152+
```python
153+
def insert_document():
154+
st.subheader("Create Document")
155+
with st.expander("Insert a new document", expanded=False):
156+
doc_id = st.text_input("Document ID", key="create_id")
157+
doc_data = st.text_area(
158+
"Document Data (JSON)",
159+
value='{\n "name": "John Doe",\n "email": "[email protected]"\n}',
160+
key="create_data"
161+
)
162+
163+
if st.button("Insert", key="create_btn"):
164+
try:
165+
json_data = json.loads(doc_data) # Using json.loads instead of eval for safety
166+
st.session_state["connection"].insert_document(doc_id, json_data)
167+
st.success("Document inserted successfully!")
168+
except Exception as e:
169+
st.error(f"Insert failed: {e}")
170+
```
171+
This function creates new documents in Couchbase by accepting a document ID and JSON data. It uses json.loads() instead of eval() for secure JSON parsing, protecting against code injection. The function displays success or error messages based on the operation outcome.
101172

102-
#### **Insert a Document**
173+
#### Read Operation
103174
```python
104-
connection.insert_document("222", {"key": "value"})
105-
st.write(connection.get_document("222"))
175+
def fetch_document():
176+
st.subheader("Read Document")
177+
with st.expander("Fetch an existing document", expanded=False):
178+
doc_id = st.text_input("Document ID to fetch", key="read_id")
179+
if st.button("Fetch", key="read_btn"):
180+
try:
181+
doc = st.session_state["connection"].get_document(doc_id)
182+
st.json(doc)
183+
except Exception as e:
184+
st.error(f"Fetch failed: {e}")
106185
```
186+
This function retrieves documents from Couchbase using their document IDs. It displays the document contents in a formatted JSON viewer if found, or shows an error message if the document doesn't exist or there's a connection issue.
107187

108-
#### **Fetch a Document**
188+
#### Update Operation
109189
```python
110-
st.write(connection.get_document("111"))
190+
def update_document():
191+
st.subheader("Update Document")
192+
with st.expander("Update an existing document", expanded=False):
193+
doc_id = st.text_input("Document ID to update", key="update_id")
194+
new_data = st.text_area(
195+
"Updated Data (JSON)",
196+
key="update_data",
197+
value='{\n "name": "John Doe",\n "email": "[email protected]"\n}',
198+
)
199+
if st.button("Update", key="update_btn"):
200+
try:
201+
json_data = json.loads(new_data) # Using json.loads instead of eval for safety
202+
st.session_state["connection"].replace_document(doc_id, json_data)
203+
st.success("Document updated successfully!")
204+
except Exception as e:
205+
st.error(f"Update failed: {e}")
111206
```
207+
This function updates existing documents by replacing their entire content with new JSON data. It requires both the document ID and the complete new document content, ensuring data consistency by using json.loads() for safe JSON parsing.
112208

113-
#### **Replace a Document**
209+
#### Delete Operation
114210
```python
115-
connection.replace_document("222", {"new_key": "new_value"})
116-
st.write(connection.get_document("222"))
211+
def delete_document():
212+
st.subheader("Delete Document")
213+
with st.expander("Delete an existing document", expanded=False):
214+
doc_id = st.text_input("Document ID to delete", key="delete_id")
215+
if st.button("Delete", key="delete_btn"):
216+
try:
217+
st.session_state["connection"].remove_document(doc_id)
218+
st.success("Document deleted successfully!")
219+
except Exception as e:
220+
st.error(f"Delete failed: {e}")
117221
```
222+
This function removes documents from the database using their document IDs. It provides immediate feedback through success/error messages and handles cases where the document might not exist.
118223

119-
#### **Delete a Document**
224+
### 3. Querying Data
120225
```python
121-
connection.remove_document("222")
122-
st.write("Document 222 deleted")
226+
def query_data():
227+
st.subheader("Query Data")
228+
with st.expander("Execute SQL++ Query", expanded=False):
229+
query = st.text_area(
230+
"SQL++ Query",
231+
value="SELECT * FROM `travel-sample`.inventory.airline LIMIT 5;",
232+
key="query_input"
233+
)
234+
if st.button("Execute Query", key="query_btn"):
235+
try:
236+
results = st.session_state["connection"].query(query)
237+
data = []
238+
for row in results:
239+
data.append(row)
240+
st.write(data)
241+
except Exception as e:
242+
st.error(f"Query failed: {e}")
123243
```
244+
This function executes SQL++ (N1QL) queries against Couchbase. The for row in results loop is necessary because Couchbase query results are returned as an iterator to efficiently handle large result sets. Converting the iterator to a list allows Streamlit to display all results at once while managing memory usage effectively.
124245

125-
#### **Run a Query**
246+
### Main function
126247
```python
127-
result = connection.query("SELECT * FROM `travel-sample`.`inventory`.`airline` LIMIT 5;")
128-
st.write(result)
248+
def main():
249+
# Initialize connection in sidebar
250+
initialize_connection()
251+
252+
# Main content area
253+
if "connection" in st.session_state:
254+
# Add tabs for different operations
255+
tab1, tab2, tab3, tab4, tab5 = st.tabs([
256+
"Create", "Read", "Update", "Delete", "Query"
257+
])
258+
259+
with tab1:
260+
insert_document()
261+
with tab2:
262+
fetch_document()
263+
with tab3:
264+
update_document()
265+
with tab4:
266+
delete_document()
267+
with tab5:
268+
query_data()
269+
else:
270+
st.info("Please connect to Couchbase using the sidebar to start.")
271+
272+
if __name__ == "__main__":
273+
st.set_page_config(
274+
page_title="Couchbase Streamlit Demo",
275+
page_icon="🔌",
276+
layout="wide"
277+
)
278+
main()
129279
```
130280

131-
## 4. Appendix
281+
## Running Your Application
282+
283+
1. **Start the Streamlit application**:
284+
```bash
285+
streamlit run app.py
286+
```
287+
288+
2. **Access the application**:
289+
- Open your browser to `http://localhost:8501`
290+
- Enter your Couchbase connection details
291+
- Start interacting with your data
292+
293+
### Verifying Changes in Couchbase Capella
294+
295+
After performing CRUD operations or queries, you can verify the changes in Couchbase Capella:
296+
297+
1. Log in to your Couchbase Capella account
298+
2. Navigate to the Query Workbench
299+
3. For CRUD operations:
300+
```sql
301+
SELECT * FROM `your-bucket`.`your-scope`.`your-collection`
302+
WHERE META().id = "your-document-id";
303+
```
304+
4. For general queries:
305+
- Use the same query you executed in your Streamlit app
306+
- Modify the query to explore related data
307+
5. You can also use the Documents browser in Capella to directly view and edit documents
308+
309+
## Conclusion
310+
This repository serves as an educational resource for developers who want to integrate Couchbase into Streamlit applications. By following these tutorials, users can learn how to query, display, and optimize Couchbase data in Streamlit apps.
311+
312+
## Appendix
132313

133314
Here are some helpful resources for working with Couchbase and Streamlit:
134315

0 commit comments

Comments
 (0)