Revise README steps and add helpful links section (documentdb#287)

shuaitian-git · web-flow · commit ebebb4329d89 · 2025-08-25T07:54:08.000+02:00
diff --git a/README.md b/README.md
@@ -142,7 +142,7 @@ singleDocumentReadResult = quickStartCollection.find_one({'name': 'John Doe'})
 
 ```
 
-Step 8: Run aggregation pipeline query
+Step 8: Run aggregation pipeline operation
 
 ```python
 
@@ -162,277 +162,9 @@ for eachDocument in results:
 
 ```
 
-## To interact directly with the PostgreSQL layer
+### Helpful Links
 
-### Pre-requisite
-
-- Ensure [Docker](https://docs.docker.com/engine/install/) is installed on your system.
-
-### Building DocumentDB with Docker
-
-Step 1: Clone the DocumentDB repo.
-
-```bash
-git clone https://github.com/microsoft/documentdb.git
-```
-
-Step 2: Create the docker image. Navigate to cloned repo.
-
-```bash
-docker build . -f .devcontainer/Dockerfile -t documentdb 
-```
-
-Note: Validate using `docker image ls`
-
-Step 3: Run the Image as a container
-
-```bash
-docker run -v $(pwd):/home/documentdb/code -it documentdb /bin/bash 
-
-cd code
-```
-
-(Aligns local location with docker image created, allows de-duplicating cloning repo again within image).<br>
-Note: Validate container is running `docker container ls`
-
-Step 4: Build & Deploy the binaries
-
-```bash
-make 
-```
-
-Note: Run in case of an unsuccessful build `git config --global --add safe.directory /home/documentdb/code` within image.
-
-```bash
-sudo make install
-```
-
-Note: To run backend postgresql tests after installing you can run `make check`.
-
-You are all set to work with DocumentDB.
-
-### Using the Prebuilt Docker Image
-
-You can use a [prebuilt docker image](https://github.com/microsoft/documentdb/pkgs/container/documentdb%2Fdocumentdb-oss/versions?filters%5Bversion_type%5D=tagged) for DocumentDB instead of building it from source.  Follow these steps:
-
-#### Pull the Prebuilt Image
-
-Pull the prebuilt image directly from the Microsoft Container Registry:
-
-```bash
-docker pull ghcr.io/microsoft/documentdb/documentdb-oss:PG16-amd64-0.105.0
-```
-
-#### Running the Prebuilt Image
-
-To run the prebuilt image, use one of the following commands:
-
-1. Run the container:
-
-```bash
-docker run -dt ghcr.io/microsoft/documentdb/documentdb-oss:PG16-amd64-0.105.0
-```
-
-2. If external access is required, run the container with parameter "-e":
-
-```bash
-docker run -p 127.0.0.1:9712:9712 -dt ghcr.io/microsoft/documentdb/documentdb-oss:PG16-amd64-0.105.0 -e
-```
-
-This will start the container and map port `9712` from the container to the host.
-
-### Connecting to the Server
-#### Internal Access
-Step 1: Run `start_oss_server.sh` to initialize the DocumentDB server and manage dependencies.
-
-```bash
-./scripts/start_oss_server.sh
-```
-
-Or logging into the container if using prebuild image
-```bash
-docker exec -it <container-id> bash
-```
-
-Step 2: Connect to `psql` shell
-
-```bash
-psql -p 9712 -d postgres
-```
-
-#### External Access
-Connect to `psql` shell
-
-```bash
-psql -h localhost --port 9712 -d postgres -U documentdb
-```
-
-## Usage directly through the PostgreSQL layer
-
-Once you have your `DocumentDB` set up running, you can start with creating collections, indexes and perform queries on them.
-
-### Create a collection
-
-DocumentDB provides [documentdb_api.create_collection](https://github.com/microsoft/documentdb/wiki/Functions#create_collection) function to create a new collection within a specified database, enabling you to manage and organize your BSON documents effectively.
-
-```sql
-SELECT documentdb_api.create_collection('documentdb','patient');
-```
-
-### Perform CRUD operations
-
-#### Insert documents
-
-The [documentdb_api.insert_one](https://github.com/microsoft/documentdb/wiki/Functions#insert_one) command is used to add a single document into a collection.
-
-```sql
-select documentdb_api.insert_one('documentdb','patient', '{ "patient_id": "P001", "name": "Alice Smith", "age": 30, "phone_number": "555-0123", "registration_year": "2023","conditions": ["Diabetes", "Hypertension"]}');
-select documentdb_api.insert_one('documentdb','patient', '{ "patient_id": "P002", "name": "Bob Johnson", "age": 45, "phone_number": "555-0456", "registration_year": "2023", "conditions": ["Asthma"]}');
-select documentdb_api.insert_one('documentdb','patient', '{ "patient_id": "P003", "name": "Charlie Brown", "age": 29, "phone_number": "555-0789", "registration_year": "2024", "conditions": ["Allergy", "Anemia"]}');
-select documentdb_api.insert_one('documentdb','patient', '{ "patient_id": "P004", "name": "Diana Prince", "age": 40, "phone_number": "555-0987", "registration_year": "2024", "conditions": ["Migraine"]}');
-select documentdb_api.insert_one('documentdb','patient', '{ "patient_id": "P005", "name": "Edward Norton", "age": 55, "phone_number": "555-1111", "registration_year": "2025", "conditions": ["Hypertension", "Heart Disease"]}');
-```
-
-#### Read document from a collection
-
-The `documentdb_api.collection` function is used for retrieving the documents in a collection.
-
-```sql
-SELECT document FROM documentdb_api.collection('documentdb','patient');
-```
-
-Alternatively, we can apply filter to our queries.
-
-```sql
-SET search_path TO documentdb_api, documentdb_core;
-SET documentdb_core.bsonUseEJson TO true;
-
-SELECT cursorPage FROM documentdb_api.find_cursor_first_page('documentdb', '{ "find" : "patient", "filter" : {"patient_id":"P005"}}');
-```
-
-We can perform range queries as well.
-
-```sql
-SELECT cursorPage FROM documentdb_api.find_cursor_first_page('documentdb', '{ "find" : "patient", "filter" : { "$and": [{ "age": { "$gte": 10 } },{ "age": { "$lte": 35 } }] }}');
-```
-
-#### Update document in a collection
-
-DocumentDB uses the [documentdb_api.update](https://github.com/microsoft/documentdb/wiki/Functions#update) function to modify existing documents within a collection.
-
-The SQL command updates the `age` for patient `P004`.
-
-```sql
-select documentdb_api.update('documentdb', '{"update":"patient", "updates":[{"q":{"patient_id":"P004"},"u":{"$set":{"age":14}}}]}');
-```
-
-Similarly, we can update multiple documents using `multi` property.
-
-```sql
-SELECT documentdb_api.update('documentdb', '{"update":"patient", "updates":[{"q":{},"u":{"$set":{"age":24}},"multi":true}]}');
-```
-
-#### Delete document from the collection
-
-DocumentDB uses the [documentdb_api.delete](https://github.com/microsoft/documentdb/wiki/Functions#delete) function for precise document removal based on specified criteria.
-
-The SQL command deletes the document for patient `P002`.
-
-```sql
-SELECT documentdb_api.delete('documentdb', '{"delete": "patient", "deletes": [{"q": {"patient_id": "P002"}, "limit": 1}]}');
-```
-
-### Collection management
-
-We can review for the available collections and databases by querying [documentdb_api.list_collections_cursor_first_page](https://github.com/microsoft/documentdb/wiki/Functions#list_collections_cursor_first_page).
-
-```sql
-SELECT * FROM documentdb_api.list_collections_cursor_first_page('documentdb', '{ "listCollections": 1 }');
-```
-
-[documentdb_api.list_indexes_cursor_first_page](https://github.com/microsoft/documentdb/wiki/Functions#list_indexes_cursor_first_page) allows reviewing for the existing indexes on a collection. We can find collection_id from `documentdb_api.list_collections_cursor_first_page`.
-
-```sql
-SELECT documentdb_api.list_indexes_cursor_first_page('documentdb','{"listIndexes": "patient"}');
-```
-
-`ttl` indexes by default gets scheduled through the `pg_cron` scheduler, which could be reviewed by querying the `cron.job` table.
-
-```sql
-select * from cron.job;
-```
-
-### Indexing
-
-#### Create an Index
-
-DocumentDB uses the `documentdb_api.create_indexes_background` function, which allows background index creation without disrupting database operations.
-
-The SQL command demonstrates how to create a `single field` index on `age` on the `patient` collection of the `documentdb`.
-
-```sql
-SELECT * FROM documentdb_api.create_indexes_background('documentdb', '{ "createIndexes": "patient", "indexes": [{ "key": {"age": 1},"name": "idx_age"}]}');
-```
-
-The SQL command demonstrates how to create a `compound index` on fields age and registration_year on the `patient` collection of the `documentdb`.
-
-```sql
-SELECT * FROM documentdb_api.create_indexes_background('documentdb', '{ "createIndexes": "patient", "indexes": [{ "key": {"registration_year": 1, "age": 1},"name": "idx_regyr_age"}]}');
-```
-
-#### Drop an Index
-
-DocumentDB uses the `documentdb_api.drop_indexes` function, which allows you to remove an existing index from a collection. The SQL command demonstrates how to drop the index named `id_ab_1` from the `first_collection` collection of the `documentdb`.
-
-```sql
-CALL documentdb_api.drop_indexes('documentdb', '{"dropIndexes": "patient", "index":"idx_age"}');
-```
-
-### Perform aggregations `Group by`
-
-DocumentDB provides the [documentdb_api.aggregate_cursor_first_page](https://github.com/microsoft/documentdb/wiki/Functions#aggregate_cursor_first_page) function, for performing aggregations over the document store.
-
-The example projects an aggregation on number of patients registered over the years.
-
-```sql
-SELECT cursorpage FROM documentdb_api.aggregate_cursor_first_page('documentdb', '{ "aggregate": "patient", "pipeline": [ { "$group": { "_id": "$registration_year", "count_patients": { "$count": {} } } } ] , "cursor": { "batchSize": 3 } }');
-```
-
-We can perform more complex operations, listing below a few more usage examples.
-The example demonstrates an aggregation on patients, categorizing them into buckets defined by registration_year boundaries.
-
-```sql
-SELECT cursorpage FROM documentdb_api.aggregate_cursor_first_page('documentdb', '{ "aggregate": "patient", "pipeline": [ { "$bucket": { "groupBy": "$registration_year", "boundaries": ["2022","2023","2024"], "default": "unknown" } } ], "cursor": { "batchSize": 3 } }');
-```
-
-This query performs an aggregation on the `patient` collection to group documents by `registration_year`. It collects unique patient conditions for each registration year using the `$addToSet` operator.
-
-```sql
-SELECT cursorpage FROM documentdb_api.aggregate_cursor_first_page('documentdb', '{ "aggregate": "patient", "pipeline": [ { "$group": { "_id": "$registration_year", "conditions": { "$addToSet": { "conditions" : "$conditions" } } } } ], "cursor": { "batchSize": 3 } }');
-```
-
-### Join data from multiple collections
-
-Let's create an additional collection named `appointment` to demonstrate how a join operation can be performed.
-
-```sql
-select documentdb_api.insert_one('documentdb','appointment', '{"appointment_id": "A001", "patient_id": "P001", "doctor_name": "Dr. Milind", "appointment_date": "2023-01-20", "reason": "Routine checkup" }');
-select documentdb_api.insert_one('documentdb','appointment', '{"appointment_id": "A002", "patient_id": "P001", "doctor_name": "Dr. Moore", "appointment_date": "2023-02-10", "reason": "Follow-up"}');
-select documentdb_api.insert_one('documentdb','appointment', '{"appointment_id": "A004", "patient_id": "P003", "doctor_name": "Dr. Smith", "appointment_date": "2024-03-12", "reason": "Allergy consultation"}');
-select documentdb_api.insert_one('documentdb','appointment', '{"appointment_id": "A005", "patient_id": "P004", "doctor_name": "Dr. Moore", "appointment_date": "2024-04-15", "reason": "Migraine treatment"}');
-select documentdb_api.insert_one('documentdb','appointment', '{"appointment_id": "A007","patient_id": "P001", "doctor_name": "Dr. Milind", "appointment_date": "2024-06-05", "reason": "Blood test"}');
-select documentdb_api.insert_one('documentdb','appointment', '{ "appointment_id": "A009", "patient_id": "P003", "doctor_name": "Dr. Smith","appointment_date": "2025-01-20", "reason": "Follow-up visit"}');
-```
-
-The example presents each patient along with the doctors visited.
-
-```sql
-SELECT cursorpage FROM documentdb_api.aggregate_cursor_first_page('documentdb', '{ "aggregate": "patient", "pipeline": [ { "$lookup": { "from": "appointment","localField": "patient_id", "foreignField": "patient_id", "as": "appointment" } },{"$unwind":"$appointment"},{"$project":{"_id":0,"name":1,"appointment.doctor_name":1,"appointment.appointment_date":1}} ], "cursor": { "batchSize": 3 } }');
-```
-
-### Community
-
-- Checkout our website at https://documentdb.io to stay up to date with the latest docs and blogs.
-- Please refer to page for contributing to our [Roadmap list](https://github.com/orgs/microsoft/projects/1407/views/1).
-- [FerretDB](https://github.com/FerretDB/FerretDB) integration allows using DocumentDB as backend engine.
+- Check out our [website](https://documentdb.io) to stay up to date with the latest on the project.
+- Check out our [docs](https://documentdb.io/docs) for MongoDB API compatibility, quickstarts and more.
 - Contributors and users can join the [DocumentDB Discord channel](https://discord.gg/vH7bYu524D) for quick collaboration.
+- Check out [FerretDB](https://github.com/FerretDB/FerretDB) and their integration of DocumentDB as a backend engine.
