GridFS.
이 페이지의 내용
개요
이 가이드 에서는 GridFS 사양을 사용하여 MongoDB 에 대용량 파일을 저장 하고 조회 하는 방법을 학습 수 있습니다. GridFS 는 대용량 파일을 청크로 분할하고 각 청크 를 별도의 문서 로 저장합니다. GridFS 에 파일 을 쿼리 하면 운전자 가 필요에 따라 청크를 어셈블합니다. GridFS 의 운전자 구현 은 파일 저장 의 운영 및 조직 을 관리하는 추상화입니다.
파일 크기가 BSON 문서 크기 제한인 16 MB를 초과하는 경우 GridFS 를 사용하세요. GridFS 는 전체 파일 을 메모리에 로드하지 않고도 파일에 액세스하는 데 유용합니다. GridFS 가 사용 사례 에 적합한지 여부에 대한 자세한 내용은 GridFS 서버 매뉴얼 페이지를 참조하세요.
GridFS 작동 방식
GridFS는 파일 청크와 파일을 설명하는 정보가 들어 있는 MongoDB 컬렉션 그룹인 버킷에 파일을 구성합니다. 버킷에는 다음과 같은 컬렉션이 포함되어 있습니다.
바이너리 파일 청크를 저장하는
chunks
컬렉션.파일 메타데이터를 저장하는
files
컬렉션.
새 GridFS 버킷을 생성하면 드라이버는 앞에 설명한 컬렉션을 생성합니다. 다른 버킷 이름을 지정하지 않는 한 기본 버킷 이름인 fs
가 컬렉션 이름 앞에 붙습니다. 드라이버는 첫 번째 쓰기 작업 중에 새 GridFS 버킷을 생성합니다.
또한 드라이버는 파일 및 관련 메타데이터를 효율적으로 검색할 수 있도록 각 컬렉션에 인덱스를 생성합니다. 인덱스가 아직 존재하지 않거나 버킷이 비어 있는 경우 드라이버가 인덱스를 생성합니다. GridFS 인덱스에 대한 자세한 내용은 GridFS 인덱스에 대한 서버 매뉴얼 페이지를 참조 하세요.
GridFS로 파일을 저장할 때 드라이버는 파일을 작은 청크로 분할하며, 각각의 청크는 chunks
컬렉션에서 별도의 문서로 표시됩니다. 또한 files
컬렉션에 파일 ID, 파일 이름 및 기타 파일 메타데이터가 포함된 문서를 만듭니다. 다음 다이어그램은 GridFS가 업로드된 파일을 분할하는 방법을 보여줍니다.
GridFS는 파일을 조회할 때 지정된 버킷의 files
컬렉션에서 메타데이터를 가져온 다음, 해당 정보를 사용하여 chunks
컬렉션의 문서에서 파일을 재구성합니다. 파일을 메모리에 입력하거나 스트림에 출력할 수 있습니다.
GridFS 사용
GridFS 작업과 이를 수행하는 방법을 알아보려면 다음 섹션으로 이동하세요.
GridFS 버킷 만들기
GridFS에서 파일을 저장하거나 조회하려면 버킷을 만들거나 MongoDB 데이터베이스에서 기존 버킷에 대한 참조를 가져오면 됩니다. GridFSBucket
인스턴스를 만들려면 데이터베이스 매개 변수를 사용하여 NewBucket()
메서드를 호출합니다.
db := client.Database("db") bucket, err := gridfs.NewBucket(db) if err != nil { panic(err) }
참고
GridFS 버킷이 이미 있는 경우 NewBucket()
메서드는 새 버킷을 인스턴스화하는 대신 버킷에 대한 참조를 반환합니다.
기본적으로 새 버킷의 이름은 fs
입니다. 사용자 지정 이름으로 버킷을 인스턴스화하려면 다음과 같이 BucketOptions
인스턴스에서 SetName()
메서드를 호출합니다.
db := client.Database("db") opts := options.GridFSBucket().SetName("custom name") bucket, err := gridfs.NewBucket(db, opts) if err != nil { panic(err) }
파일 업로드
다음 방법 중 하나를 사용하여 GridFS 버킷에 파일을 업로드할 수 있습니다.
입력 스트림에서 읽는
UploadFromStream()
메서드를 사용합니다.출력 스트림에 쓰는
OpenUploadStream()
메서드를 사용합니다.
두 업로드 프로세스에서 UploadOptions
인스턴스에 대한 구성 정보를 지정할 수 있습니다. UploadOptions
필드의 전체 목록은 API 설명서를 참조하세요.
입력 스트림을 사용하여 업로드
입력 스트림을 사용하여 파일을 업로드하려면 다음 매개 변수와 함께 UploadFromStream()
메서드를 사용합니다.
파일 이름
열린 파일을 매개 변수로 사용하는
io.Reader
UploadFromStream()
의 동작을 수정하는 선택적opts
매개 변수
다음 코드 예시에서는 file.txt
라는 파일에서 읽고 콘텐츠를 GridFS 버킷에 업로드합니다. opts
매개 변수를 사용하여 파일 메타데이터를 설정합니다.
file, err := os.Open("path/to/file.txt") uploadOpts := options.GridFSUpload().SetMetadata(bson.D{{"metadata tag", "first"}}) objectID, err := bucket.UploadFromStream("file.txt", io.Reader(file), uploadOpts) if err != nil { panic(err) } fmt.Printf("New file uploaded with ID %s", objectID)
출력 스트림을 사용하여 업로드
출력 스트림을 사용하여 파일을 업로드하려면 다음 매개 변수와 함께 OpenUploadStream()
메서드를 사용합니다.
파일 이름
OpenUploadStream()
의 동작을 수정하는 선택적opts
매개 변수
다음 코드 예시에서는 GridFS 버킷에서 업로드 스트림을 열고 opts
매개 변수를 사용하여 각 청크의 바이트 수를 설정합니다. 그러면 file.txt
의 콘텐츠에 Write()
메서드가 호출되어 해당 콘텐츠가 스트림에 기록됩니다.
file, err := os.Open("path/to/file.txt") if err != nil { panic(err) } uploadOpts := options.GridFSUpload().SetChunkSizeBytes(200000) uploadStream, err := bucket.OpenUploadStream("file.txt", uploadOpts) if err != nil { panic(err) } fileContent, err := io.ReadAll(file) if err != nil { panic(err) } var bytes int if bytes, err = uploadStream.Write(fileContent); err != nil { panic(err) } fmt.Printf("New file uploaded with %d bytes written", bytes)
파일 정보 검색
GridFS 버킷의 files
컬렉션에 저장된 파일 메타데이터를 조회할 수 있습니다. files
컬렉션의 각 문서에는 다음 정보가 포함되어 있습니다.
파일 ID
파일 길이
최대 청크 크기
업로드 날짜 및 시간
파일 이름
다른 정보를 저장할 수 있는
metadata
문서입니다.
파일 데이터를 조회하려면 GridFSBucket
인스턴스에서 Find()
메서드를 호출합니다. 특정 파일 문서만 일치시키려면 쿼리 필터를 Find()
에 인수로 전달하면 됩니다.
참고
Find()
메서드에서는 쿼리 필터를 매개 변수로 사용해야 합니다. files
컬렉션의 모든 문서를 일치시키려면 빈 쿼리 필터를 Find()
에 전달합니다.
다음 예에서는 files
컬렉션에서 length
값이 1500
보다 큰 문서의 파일 이름과 길이를 조회합니다.
filter := bson.D{{"length", bson.D{{"$gt", 1500}}}} cursor, err := bucket.Find(filter) if err != nil { panic(err) } type gridfsFile struct { Name string `bson:"filename"` Length int64 `bson:"length"` } var foundFiles []gridfsFile if err = cursor.All(context.TODO(), &foundFiles); err != nil { panic(err) } for _, file := range foundFiles { fmt.Printf("filename: %s, length: %d\n", file.Name, file.Length) }
파일 다운로드
다음 방법 중 하나를 사용하여 GridFS 파일을 다운로드할 수 있습니다.
DownloadToStream()
메서드를 사용하여 파일을 출력 스트림에 다운로드합니다.OpenDownloadStream()
메서드를 사용하여 입력 스트림을 엽니다.
출력 스트림에 파일 다운로드
DownloadToStream()
메서드를 사용하여 GridFS 버킷의 파일을 출력 스트림에 직접 다운로드할 수 있습니다. DownloadToStream()
은 파일 ID와 함께 io.Writer
를 매개 변수로 사용합니다. 이 메서드는 지정된 파일 ID를 가진 파일을 다운로드하여 io.Writer
에 기록합니다.
다음은 파일을 다운로드하여 파일 버퍼에 기록하는 예입니다.
id, err := primitive.ObjectIDFromHex("62f7bd54a6e4452da13b3e88") fileBuffer := bytes.NewBuffer(nil) if _, err := bucket.DownloadToStream(id, fileBuffer); err != nil { panic(err) }
입력 스트림에 파일 다운로드
OpenDownloadStream()
메서드를 사용하여 입력 스트림을 통해 GridFS 버킷의 파일을 메모리에 다운로드할 수 있습니다. OpenDownloadStream()
은 파일 ID를 매개 변수로 사용하고 파일을 읽을 수 있는 입력 스트림을 반환합니다.
다음 예에서는 파일을 메모리에 다운로드하고 해당 콘텐츠를 읽습니다.
id, err := primitive.ObjectIDFromHex("62f7bd54a6e4452da13b3e88") downloadStream, err := bucket.OpenDownloadStream(id) if err != nil { panic(err) } fileBytes := make([]byte, 1024) if _, err := downloadStream.Read(fileBytes); err != nil { panic(err) }
파일 이름 바꾸기
Rename()
메서드를 사용하여 버킷에 있는 GridFS 파일의 이름을 업데이트할 수 있습니다. 파일 ID 값과 새 filename
값을 인수로 Rename()
에 전달합니다.
다음 예에서는 파일 이름을 "mongodbTutorial.zip"
으로 변경합니다.
id, err := primitive.ObjectIDFromHex("62f7bd54a6e4452da13b3e88") if err := bucket.Rename(id, "mongodbTutorial.zip"); err != nil { panic(err) }
파일 삭제
Delete()
메서드를 사용하여 GridFS 버킷에서 파일을 제거할 수 있습니다. 파일 ID 값을 인수로 Delete()
에 전달합니다.
다음은 파일을 삭제하는 예입니다.
id, err := primitive.ObjectIDFromHex("62f7bd54a6e4452da13b3e88") if err := bucket.Delete(id); err != nil { panic(err) }
GridFS 버킷 삭제
Drop()
메서드를 사용하여 GridFS 버킷을 삭제할 수 있습니다.
다음 코드 예시에서는 GridFS 버킷을 삭제합니다.
if err := bucket.Drop(); err != nil { panic(err) }
추가 리소스
GridFS와 그 운영에 대해 자세히 알아보려면 GridFS 매뉴얼 페이지를 방문하세요.
API 문서
이 가이드에 설명된 메서드 또는 유형에 대해 자세히 알아보려면 다음 API 설명서를 참조하세요.