Skip to content

docs: improve Weaviate knowledge guide #32

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
manthansingh26 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: improve Weaviate knowledge guide #32

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 42 additions & 0 deletions Knowledge/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,13 @@ REST Endpoint: https://larnd9rle1zwapsdcqw.c0.us-east1.gcp.weaviate.cloud
gRPC Endpoint: https://grpc-larnd9rle1zwapsdcqw.c0.us-east1.gcp.weaviate.cloud
ReadOnly API Key: Z0lQNXFDVnFnRmV6OTZRdF9KRVUwVzFEdjgxaHIvVFB3dkFyV0JqSnFxWFJYMWhqM0FTQ0NncU14S2hrPV92MjAw
```
## Required Environment Variables

| Variable | Required | Description |
|-----------|-----------|------------|
| WEAVIATE_URL | Yes | Weaviate cluster URL |
| WEAVIATE_API_KEY | Yes | Read-only API key for database access |
| OPENAI_APIKEY | Yes | OpenAI API key used for embeddings and generation |
Comment on lines +14 to +20

@coderabbitai coderabbitai Bot May 26, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add blank line before heading.

Markdown convention requires a blank line before headings for proper parsing. As per static analysis.

📝 Proposed fix 


    

  • 



Required Environment Variables


</details>

<details>
<summary>🧰 Tools</summary>

<details>
<summary>🪛 markdownlint-cli2 (0.22.1)</summary>

[warning] 14-14: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Above

(MD022, blanks-around-headings)

</details>

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>




Verify each finding against current code. Fix only still-valid issues, skip the

rest with a brief reason, keep changes minimal, and validate.


In @Knowledge/README.md around lines 14 - 20, Add a single blank line

immediately before the "## Required Environment Variables" heading in

Knowledge/README.md so the Markdown parser recognizes the heading correctly;

locate the heading text "## Required Environment Variables" and insert one empty

line above it.



</details>

<!-- fingerprinting:phantom:triton:puma -->

<!-- This is an auto-generated comment by CodeRabbit -->


    

  
  




    


        

      
  
  

    
  
    
    

  

  

  



          

              

      








    


  





        

    


    


  		



    

    

    

  
    







    

    

    

  
    ## 1. Database Connection






    

    

    

  
    







      

    
          
            
          
          Expand Down
          
            
          
          Expand Up
    
    @@ -256,5 +263,40 @@ refined_response = content.generate.near_text(
  


    

    

    

  
        limit=10






    

    

    

  
    )






    

    

    

  
    ```






    

    

    

  
    ## Troubleshooting






      


  
        

      
    
      

        

          



  

    

        

        

  

    

      
          @coderabbitai
      

      
            coderabbitai
  Bot

      

      

      


        May 26, 2026



      
    


  


  

    

      

          
    
    

  


        
            
  
      
              Copy link

  

              
  
      
                Copy Markdown

  

        
      

    


    

        



        

    

  




        

      

  

  
 

  
    

    
Choose a reason for hiding this comment


    

      The reason will be displayed to describe this comment to others. Learn more.
    


    

      
      



  



  
    

      
⚠️ Potential issue | 🟡 Minor | ⚡ Quick win


Add blank line before heading.


Markdown convention requires a blank line before headings. As per static analysis.



📝 Proposed fix



    

  • 



Troubleshooting


</details>

<details>
<summary>🧰 Tools</summary>

<details>
<summary>🪛 markdownlint-cli2 (0.22.1)</summary>

[warning] 266-266: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Above

(MD022, blanks-around-headings)

</details>

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>




Verify each finding against current code. Fix only still-valid issues, skip the

rest with a brief reason, keep changes minimal, and validate.


In @Knowledge/README.md at line 266, Insert a single blank line immediately

before the "## Troubleshooting" heading in Knowledge/README.md so the markdown

heading is separated by an empty line from the previous paragraph or block;

locate the "## Troubleshooting" heading and add one newline above it.



</details>

<!-- fingerprinting:phantom:triton:puma -->

<!-- This is an auto-generated comment by CodeRabbit -->


    

  
  




    


        

      
  
  

    
  
    
    

  

  

  



          

              

      








    


  





        

    


    


  		



    

    

    

  
    







    

    

    

  
    ### Authentication Errors






    

    

    

  
    







    

    

    

  
    If connection attempts fail:






    

    

    

  
    







    

    

    

  
    - Verify that `WEAVIATE_URL` is configured correctly.






    

    

    

  
    - Verify that `WEAVIATE_API_KEY` is present in your environment.






    

    

    

  
    - Verify that `OPENAI_APIKEY` is configured when using OpenAI-powered features.






      


  
        

      
    
      

        

            

      

      Comment on lines

    
      +272
     to 
      +274
    

  


  





  

    

        

        

  

    

      
          @coderabbitai
      

      
            coderabbitai
  Bot

      

      

      


        May 26, 2026



      
    


  


  

    

      

          
    
    

  


        
            
  
      
              Copy link

  

              
  
      
                Copy Markdown

  

        
      

    


    

        



        

    

  




        

      

  

  
 

  
    

    
Choose a reason for hiding this comment


    

      The reason will be displayed to describe this comment to others. Learn more.
    


    

      
      



  



  
    

      
🧹 Nitpick | 🔵 Trivial | ⚡ Quick win


Rephrase to avoid repetitive sentence structure.


Three consecutive sentences begin with "Verify that", which degrades readability. Consider varying the structure. As per static analysis.



📝 Proposed fix

-- Verify that `WEAVIATE_URL` is configured correctly.
-- Verify that `WEAVIATE_API_KEY` is present in your environment.
-- Verify that `OPENAI_APIKEY` is configured when using OpenAI-powered features.
+- Check that `WEAVIATE_URL` is configured correctly.
+- Ensure `WEAVIATE_API_KEY` is present in your environment.
+- Verify `OPENAI_APIKEY` is configured when using OpenAI-powered features.






📝 Committable suggestion



‼️ IMPORTANT

Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.



  

    

      

        Suggested change
      

    

    

      

          

            
            - Verify that `WEAVIATE_URL` is configured correctly.
          

          

            
            - Verify that `WEAVIATE_API_KEY` is present in your environment.
          

          

            
            - Verify that `OPENAI_APIKEY` is configured when using OpenAI-powered features.
          

          

            
            - Check that `WEAVIATE_URL` is configured correctly.
          

          

            
            - Ensure `WEAVIATE_API_KEY` is present in your environment.
          

          

            
            - Verify `OPENAI_APIKEY` is configured when using OpenAI-powered features.
          

      

    

    

  







🧰 Tools


🪛 LanguageTool

[style] ~274-~274: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.

Context: ..._KEYis present in your environment. - Verify thatOPENAI_APIKEY` is configured when...


(ENGLISH_WORD_REPEAT_BEGINNING_RULE)







🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@Knowledge/README.md` around lines 272 - 274, Reword the three checklist lines
to avoid repeating "Verify that" while keeping the same checks; for example,
combine/variant them to: ensure WEAVIATE_URL is configured correctly, confirm
WEAVIATE_API_KEY is present in your environment, and set OPENAI_APIKEY when
using OpenAI-powered features—refer to the environment variables WEAVIATE_URL,
WEAVIATE_API_KEY, and OPENAI_APIKEY in the updated copy.






    

  
  




    


        

      
  
  

    
  
    
    

  

  

  



          

              

      








    


  





        

    


    


  		



    

    

    

  
    







    

    

    

  
    ### Empty Search Results






    

    

    

  
    







    

    

    

  
    If searches return no useful results:






    

    

    

  
    







    

    

    

  
    - Try broader search queries.






    

    

    

  
    - Increase the result limit.






    

    

    

  
    - Test hybrid search instead of vector-only search.






    

    

    

  
    - Verify that the target collection contains indexed data.






    

    

    

  
    ### OpenAI Integration Errors






      


  
        

      
    
      

        

          



  

    

        

        

  

    

      
          @coderabbitai
      

      
            coderabbitai
  Bot

      

      

      


        May 26, 2026



      
    


  


  

    

      

          
    
    

  


        
            
  
      
              Copy link

  

              
  
      
                Copy Markdown

  

        
      

    


    

        



        

    

  




        

      

  

  
 

  
    

    
Choose a reason for hiding this comment


    

      The reason will be displayed to describe this comment to others. Learn more.
    


    

      
      



  



  
    

      
⚠️ Potential issue | 🟡 Minor | ⚡ Quick win


Add blank line before heading.


Markdown convention requires a blank line before headings. As per static analysis.



📝 Proposed fix

 - Verify that the target collection contains indexed data.
+
 ### OpenAI Integration Errors






📝 Committable suggestion



‼️ IMPORTANT

Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.



  

    

      

        Suggested change
      

    

    

      

          

            
            ### OpenAI Integration Errors
          

          

            
            - Verify that the target collection contains indexed data.
          

          

            
            
          

          

            
            ### OpenAI Integration Errors
          

      

    

    

  







🧰 Tools


🪛 markdownlint-cli2 (0.22.1)

[warning] 284-284: Headings should be surrounded by blank lines

Expected: 1; Actual: 0; Above


(MD022, blanks-around-headings)







🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@Knowledge/README.md` at line 284, Add a blank line immediately before the
heading "### OpenAI Integration Errors" in Knowledge/README.md so the heading is
separated from the preceding content per Markdown convention; locate the "###
OpenAI Integration Errors" heading and insert a single empty line above it
(ensure no extra spacing beyond one blank line).






    

  
  




    


        

      
  
  

    
  
    
    

  

  

  



          

              

      








    


  





        

    


    


  		



    

    

    

  
    







    

    

    

  
    Common causes include:






    

    

    

  
    







    

    

    

  
    - Invalid API credentials.






    

    

    

  
    - OpenAI rate limits.






    

    

    

  
    - Network connectivity issues.






    

    

    

  
    







    

    

    

  
    Refer to OpenAI API logs for additional debugging information.






    

    

    

  
    







    

    

    

  
    ### Slow Retrieval Performance






    

    

    

  
    







    

    

    

  
    If retrieval is slower than expected:






    

    

    

  
    







    

    

    

  
    - Reduce result limits.






    

    

    

  
    - Apply filters before generation.






    

    

    

  
    - Use retrieval and re-ranking patterns only when higher quality results are required.






    

    

    

  
    







    

    

    

  
    Note: Always refer to [OpenAI's documentation](https://platform.openai.com/docs) and [Weaviate's documentation](https://weaviate.io/developers/weaviate) for the most up-to-date information.